While creating or revising any program for the Macintosh, you should be aware of the most common reasons why programs fail on various versions of the Macintosh. This note will detail some common failure modes, why they occur, and how to avoid them.
We’ve tried to explain the issues in depth, but recognize that not everyone is interested in every issue. For example, if your application is not copy protected, you’re probably not very interested in the section on copy protection. That’s why we’ve included the outline form of the technical note. The first two pages outline the problems and the solutions that are detailed later. Feel free to skip around at will, but remember that we’re sending this enormous technical note because the suggestions it provides may save you hasty compatibility revisions when we announce a new machine.
We know it’s a lot, and we’re here to help you if you need it. Our address (electronic and physical) is on page two—contact us with any questions—that’s what we’re here for!
Compatibility: the outline
Don’t assume the screen is a fixed size
To get the screen size:
• check the QuickDraw global screenBits.bounds
Don’t assume the screen is in a fixed location
To get the screen location:
• check the QuickDraw global screenBits.baseAddr
Don’t assume that rowBytes is equal to the width of the screen
To get the number of bytes on a line:
• check the QuickDraw global screenBits.rowBytes
To get the screen width:
• check the QuickDraw global screenBits.bounds.right
To do screen-size calculations:
• Use LongInts
Don’t write to or read from nil Handles or nil Pointers
Don’t create or Use Fake Handles
To avoid creating or using fake handles:
• Always let the Memory Manager perform operations with handles
• Never write code that assigns something to a master pointer
Don’t write code that modifies itself
Self modifying code will not live across incarnations of the 68000
Think carefully about code designed strictly as copy protection
To avoid copy protection-related incompatibilities:
• Avoid copy protection altogether
• Rely on schemes that don’t require specific hardware
• Make sure your scheme doesn’t perform illegal operations
Don’t ignore errors
To get valuable information:
• Check all pertinent calls for errors
• Always write defensive code
Don’t access hardware directly
To avoid hardware-related incompatibilities:
• Don’t read or write the hardware
• If you can’t get the support from the ROM, ask the system where the hardware is
• Use low-memory globals
Don’t use bits that are reserved
To avoid compatibility problems when bit status changes:
• Don’t use undocumented stuff
• When using low-memory globals, check only what you want to know
Summary
Minor bugs are getting harder and harder to get away with:
• Good luck
• We’ll help
• AppleLink: MacDTS, MCI: MacDTS
• U.S. Mail: 20525 Mariani Ave.; M/S 27-T; Cupertino, CA 95014
What it Is
The basic idea is to make sure that your programs will run, regardless of which Macintosh they are being run on. The current systems to be concerned with include:
• Macintosh 128K • Macintosh 512Ke
• Macintosh 512K • Macintosh Plus
• Macintosh XL • Macintosh SE
• Macintosh II
If you perform operations in a generic fashion, there is rarely any reason to know what machine is running. This means that you should avoid writing code to determine which version of the machine you are running on, unless it is absolutely necessary.
For the purposes of this discussion, the term “programs” will be used to describe any code that runs on a Macintosh. This includes applications, INITs, FKEYs, Desk Accessories and Drivers.
What the “Rules” mean
Compatibility across all Macintosh computers (which may sound like it involves more work for you) may actually mean that you have less work to do, since it may not be necessary to revise your program each time Apple brings out a new computer or System file. Users, as a group, do not understand compatibility problems; all they see is that the program does not run on their system.
The benefits of being compatible are many-fold: your customers/users stay happy, you have less programming to do, you can devote your time to more valuable goals, there are fewer versions to deal with, your code will probably be more efficient, your users will not curse you under their breath, and your outlook on life will be much merrier.
Now that we know what being compatible is all about, recognize that nobody is requiring you to be compatible with anything. Apple does not employ roving gangs of thought police to be sure that developers are following the recommended guidelines. Furthermore, when the guidelines comprise 1200 pages of turgid prose (Inside Macintosh), you can be expected to miss one or two of the “rules.” It is no sin to be incompatible, nor is it a punishable offense. If it were, there would be no Macintosh programs, since virtually all developers would be incarcerated. What it does mean, however, is that your program will be unfavorably viewed until it steps in line with the current system (which is a moving target). If a program becomes incompatible with a new Macintosh, it usually requires rethinking the offending code, and releasing a new version. You may read something like “If the developers followed Apple guidelines, they would be compatible with the transverse-hinged diatomic quark realignment system.” This means that if you made any mistakes (you read all 1200 pages carefully, right?), you will not be compatible. It is extremely difficult to remain completely compatible, particularly in a system as complex as the Macintosh. The rules haven’t changed, but what you can get away with has. There are, however, a number of things that you can do to improve your odds—some of which will be explained here.
It’s your choice
It is still your choice whether you will be concerned with compatibility or not. Apple will not put out a warrant for your arrest. However, if you are doing things that are specifically illegal, Apple will also not worry about “breaking” your program.
Bad Things
The following list is not intended to be comprehensive, but these are the primary reasons why programs break from one version of the system to the next. These are the current top ten commandments:
I Thou shalt not assume the screen is a fixed size.
II Thou shalt not assume the screen is at a fixed location.
III Thou shalt not assume that rowBytes is equal to the width of the screen.
IV Thou shalt not use nil handles or nil pointers.
V Thou shalt not create or use fake handles.
VI Thou shalt not write code that modifies itself.
VII Thou shalt think twice about code designed strictly as copy protection.
VIII Thou shalt check errors returned as function results.
IX Thou shalt not access hardware directly.
X Thou shalt not use any of the bits that are reserved (unused means reserved).
This has been determined from extensive testing of our diverse software base.
Assuming the screen is a fixed size
Do not assume that the Macintosh screen is 512 x 342 pixels. Programs that do generally have problems on (or special case for) the Macintosh XL, which has a wider screen. Most applications have to create the bounding rectangle where a window can be dragged. This is the boundsRect that is passed to the call:
Some ill-advised programs create the boundsRect by something like:
SetRect (boundsRect, 0,0,342,512); { oops, this is hard-coded…}
Why it’s Bad
This is bad because it is never necessary to specifically put in the bounding rectangle for the screen. On a Macintosh XL for example, the screen size is 760x364 (and sometimes 608x431 with alternate hardware). If a program uses the hard-coded 0,0,342,512 as a bounding rectangle, end users will not be able to move their windows past the fictitious boundary of 512. If something similar were done to the GrowWindow call, it would make it impossible for users to grow their window to fill the entire screen. (Always a saddening waste of valuable screen real-estate.)
Assuming screen size makes it more difficult to use the program on Macintoshes with big screens, by making it difficult to grow or move windows, or by drawing in strange places where they should not be drawing (outside of windows). Consider the case of running on a Macintosh equipped with one of the full page displays, or Ultra-Large screens. No one who paid for a big screen wants to be restricted to using only the upper-left corner of it.
How to avoid becoming a screening fascist
Never hard code the numbers 512 and 342 for screen dimensions. You should avoid using constants for system values that can change. Parameters like these are nearly always available in a dynamic fashion. Programs should read the appropriate variables while the program is running (at run-time, not at compile time).
Here’s how smart programs get the screen dimensions:
InitGraf(@thePort); { QuickDraw global variables have to be initialized.}
…
boundsRect := screenBits.bounds; { The Real way to get screen size }
{ Use QuickDraw global variable. }
This is smart, because the program never has to know specifically what the numbers are. All references to rectangles that need to be related to the screen (like the drag and grow areas of windows) should use screenBits.bounds to avoid worrying about the screen size.
Note that this does not do anything remotely like assume that “if the computer is not a standard Macintosh, then it must be an XL.” Special casing for the various versions of the Macintosh has always been suspicious at best; it is now grounds for breaking. (At least with respect to screen dimensions.)
By the way, remember to take into account the menu bar height when using this rectangle. On 128K ROMs (and later) you can use the low-memory global mBarHeight (a word at $BAA). But since we didn’t provide a low-memory global for the menu bar height in the 64K ROMs, you’ll have to hard code it to 20 ($14). (You’re not the only ones to forget the future holds changes.)
How to find fascist screenism in current programs
The easiest way is to exercise your program on one of the Ultra-Large screen Macintoshes. There should be no restrictions on sizing or moving the windows, and all drawing should have no problems. If there are any anomalies in the program’s usage, there is probably a lurking problem. Also, do a global find in the source code to see if the numbers 512 or 342 occur in the program. If so, and if they are in reference to the screen, excise them.
Assuming the screen is at a fixed location
Some programs use a fixed screen address, assuming that the screen location will be the same on various incarnations of the Macintosh. This is not the case. For example, the screen is located at memory location $1A700 on a 128K Macintosh, at $7A700 on a 512K Macintosh, at $F8000 on the Macintosh XL, and at $FA700 on the Macintosh Plus.
Why it’s Bad
When a program relies upon the screen being in a fixed location, Murphy’s Law dictates that an unknowing user will run it upon a computer with the screen in a different location. This usually causes the system to crash, since the offending program will write to memory that was used for something important. Programs that crash have been proven to be less useful than those that don’t.
How to avoid being a base screener
Suffice it to say that there is no way that the address of the screen will remain static, but there are rare occasions where it is necessary to go directly to the screen memory. On these occasions, there are bad ways and not-as-bad ways to do it. A bad way:
myScreenBase := Pointer ($7A700); { not good. Hard-coded number. }
A not-as-bad way:
InitGraf(@thePort); { do this only once in a program. }
Using the latter approach is guaranteed to work, since QuickDraw has to know where to draw, and the operating system tells QuickDraw where the screen can be found. When in doubt, ask QuickDraw. This will work on Macintosh computers from now until forever, so if you use this approach you won’t have to revise your program just because the screen moved in memory.
If you have a program (such as an INIT) that cannot rely upon QuickDraw being initialized (via InitGraf), then it is possible to use the ScrnBase low-memory global variable (a long word at $824). This method runs a distant second to asking QuickDraw, but is sometimes necessary.
How to find base screeners
The easiest way to find base screeners is to run the offending program on machines that have different screen addresses. If any addresses are being used in a base manner, the system will usually crash. The offending program may also occasionally refuse to draw. Some programs afflicted with this problem may also hang the computer (sometimes known as accessing funny space). Also, do a global find on the source code to look for numbers like $7A700 or $1A700. When found, exercise caution while altering the offending lines.
Assuming that rowbytes is equal to the width of the screen
According to the definition of a bitMap found in Inside Macintosh (p I-144), you can see that rowBytes is the number of actual bytes in memory that are used to determine the bitMap. We know the screen is just a big hunk of memory, and we know that QuickDraw uses that memory as a bitMap. rowBytes accomplishes the translation of a big hunk of memory into a bitMap. To do this, rowBytes tells the system how long a given row is in memory and, more importantly, where in memory the next row starts. For conventional Macintoshes, rowBytes (bytes per Row) * 8 (Pixels per Byte) gives the final horizontal width of the screen as Pixels per Row. This does not have to be the case. It is possible to have a Macintosh screen where the rowBytes extends beyond what is actually visible on the screen. You can think of it as having the screen looking in on a larger bitMap. Diagrammatically, it might look like:
With an Ultra-Large screen, the number of bytes used for screen memory may be in the 500,000 byte range. Whenever calculations are being made to find various locations in the screen, the variables used should be able to handle larger screen sizes. For example, a 16 bit Integer will not be able to hold the 500,000 number, so a LongInt would be required. Do not assume that the screen size is 21,888 bytes long. bitMaps can be larger than 32K or 64K.
Why it’s Bad
Programs that assume that all of the bytes in a row are visible may make bad calculations, causing drawing routines to produce unusual, and unreadable, results. Also, programs that use the rowBytes to figure out the width of the screen rectangle will find that their calculated rectangle is not the real screenBits.Bounds. Drawing into areas that are not visible will not necessarily crash the computer, but it will probably give erroneous results, and displays that don’t match the normal output of the program.
Programs that assume that the number of bytes in the screen memory will be less than 32768 may have problems drawing into Ultra-Large screens, since those screens will often have more memory than a normal Macintosh screen. These particular problems do not evidence themselves by crashing the system. They generally appear as loss of functionality (not being able to move a window to the bottom of the screen), or as drawing routines that no longer look correct. These problems can prevent an otherwise wonderful program from being used.
How to avoid being a row byter
In any calculations, the rowBytes variable should be thought of as the way to get to the next row on the screen. This is distinct from thinking of it as the width of the screen. The width should always be found from screenBits.bounds.right– screenBits.bounds.left.
It is also inappropriate to use the rectangle to decide how many bytes there are on a row. Programs that do something like:
bytesLine := screenBits.bounds.right DIV 8; { bad use of bounds }
rightSide := screenBits.rowBytes * 8; { bad use of rowBytes }
will find that the screen may have more rowBytes than previously thought. The best way to avoid being a row byter is to use the proper variables for the proper things. Without the proper mathematical basis to the screen, life becomes much more difficult. Always do things like:
bytesLine := screenBits.rowBytes; { always the correct number }
rightSide := screenBits.bounds.right; { always the correct screen size }
It is sometimes necessary to do calculations involving the screen. If so, be sure to use LongInts for all the math, and be sure to use the right variables (i.e. use LongInts). For example, if we need to find the address of the 500th row in the screen (500 lines from the top):
VAR myAddress: LongInt;
myRow: LongInt; { so the calculations don’t round off. }
myOffset: LongInt; { could easily be over 32768 ... }
bytesLine: LongInt;
myAddress := ord4(screenBits.baseAddr);{start w/the real base address }
myRow := 500; {the row we want to address }
bytesLine := screenBits.rowBytes; {the real bytes per line }
myAddress := myAddress + myOffset; {final address of the 500th line }
This is not something you want to do if you can possibly avoid it, but if you simply must go directly to the screen, be careful. The big-screen machines (Ultra-Large screens) will thank you for it. If QuickDraw cannot be initialized, there is also the low-memory global screenRow (a word at $106) that will give you the current rowBytes.
How to find row byters
To find current problems with row byter programs, run them on a machine equipped with Ultra-Large screens and see if any anomalies crop up. Look for drawing sequences that don’t work right, and for drawing that clips to an imaginary edge. For source-level inspection, look for uses of the rowBytes variables and be sure that they are being used in a mathematically sound fashion. Be highly suspicious of any code that uses rowBytes for the screen width. Any calculations involving those system variables should be closely inspected for round-off errors and improper use. Search for the number 8. If it is being used in a calculation where it is the number of bits per byte, then watch that code closely for improper conceptualization. This is code that could leap out and grab you by the throat at anytime. Be careful!
Using nil Handles or nil Pointers
A nil pointer is a pointer that has a value of 0. Recognize that pointers are merely addresses in memory. This means that a nil pointer is pointing to memory location 0. Any use of memory location 0 is strictly forbidden, since it is owned by Motorola. Trespassers may be shot on sight, but they may not die until much later. Sometimes trespassers are only wounded and act strangely. Any use of memory location 0 can be considered a bug, since there are no valid reasons for Macintosh programs to read or write to that memory. However, nil pointers themselves are not necessarily bad. It is occasionally necessary to pass nil pointers to ROM routines. This should not be confused with reading or writing to memory location 0. A pointer normally points to (contains the address of) a location in memory. It could look like this:
If a pointer has been cleared to nil, it will point to memory location 0. This is OK as long as the program does not try to read from or write to that pointer. An example of a nil pointer could look like:
nil handles are related to the problem, since a handle is merely the address of a pointer (or a pointer to a pointer). An example of what a normal handle might look like is:
If the memory at 0 contains an odd number (numerically odd), then using it as a pointer will cause a system error with ID=2. This can be very useful, since that tells you exactly where the program is using this illegal handle, making it easy to fix. Unfortunately, there are cases where it is appropriate to pass a nil handle to ROM routines (such as GetScrap). These cases are rare, and it is never legal to read from or write to a nil handle.
There is also the case of an empty handle. An empty handle is one where the handle itself (the first pointer) points to a valid place in memory; that place in memory is also a pointer, and if it is nil the entire handle is termed empty. There are occasions where it is necessary to use the handle itself, but using the nil pointer that it contains is not valid. An example of an empty handle could be:
Why it’s Bad
The use of nil pointers can lead to the use of make-believe data. This make-believe data often changes for different versions of the computer. This changing data makes it difficult to predict what will happen when a program uses nil pointers. Programs may not crash as a result of using a nil pointer, and they may behave in a consistent fashion. This does not mean that there isn’t a bug. This merely means that the program is lucky, and that it should be playing the lottery, not running on a Macintosh. If a program acts differently on different versions of the Macintosh, you should think “could there be a nasty nil pointer problem here?” Use of a nil handle usually culminates in reading or writing to obscure places in memory. As an example:
VAR myHandle: TEHandle;
myHandle := nil;
That’s pretty straightforward, so what’s the problem? If you do something like:
myHandle^^.viewRect := myRect; { very bad idea with myHandle = nil }
memory location zero will be used as a pointer to give the address of a TextEdit record. What if that memory location points to something in the system heap? What if it points to the sound buffer? In cases like these, eight bytes of rectangle data will be written to wherever memory location 0 points.
Use of a nil handle will never be useful. This memory is reserved and used by the 68000 for various interrupt vectors and Valuable Stuff. This Valuable Stuff is composed of things that you definitely do not want to change. When changed, the 68000 finds out, and decides to get back at your program in the most strange and wonderful ways. These strange results can range from a System Error all the way to erasing hard disks and destroying files. There really is no limit to the havoc that can be wreaked. This tends to keep the users on the edge of their seat, but this is not really the desired effect. As noted above, it won’t necessarily cause traumatic results. A program can be doing naughty things and not get caught. This is still a bug that needs to be fixed, since it is nearly guaranteed to give different results on different versions of the Macintosh. Programs exhibiting schizophrenia have been proven to be less enjoyable to use.
How to avoid being a Niller
Whenever a program uses pointers and handles, it should ensure that the pointer or handle will not be nil. This could be termed defensive programming, since it assumes that everyone is out to get the program (which is not far from the truth on the Macintosh). You should always check the result of routines that claim to pass back a handle. If they pass you back a nil handle, you could get in trouble if you use them. Don’t trust the ROM. The following example of a defensive use of a handle involves the Resource Manager. The Resource Manager passes back a handle to the resource data. There are any number of places where it may be forced to pass back a nil handle. For example:
VAR myRezzie: MyHandle;
myRezzie := MyHandle(GetResource(myResType, myResNumber)); { could be missing…}
IF myRezzie = nil THEN ErrorHandler('We almost got Nilled')
ELSE myRezzie^^.myRect := newRect; { We know it is OK }
As another example, think of how handles can be purged from memory in tight memory conditions. If a block is marked purgeable, the Memory Manager may throw it away at any time. This creates an empty handle. The defensive programmer will always make sure that the handles being used are not empty.
VAR myRezzie: myHandle;
myRezzie := myHandle(GetResource(myResType, myResNumber)); { could be missing… }
IF myRezzie = nil THEN ErrorHandler('We almost got Nilled')
ELSE myRezzie^^.myRect := newRect; { We know it is OK }
tempHandle := NewHandle (largeBlock); {might dispose a purgeable myRezzie}
IF myRezzie^ = nil THEN LoadResource(Handle(myRezzie)); {Re-load empty handle}
IF ResError = noErr THEN
myRezzie^^.StatusField := OK; { guaranteed not empty, and actually gets read back in, if necessary }
Be especially careful of places where memory is being allocated. The NewHandle and NewPtr calls will return a nil handle or pointer if there is not enough memory. If you use that handle or pointer without checking, you will be guilty of being a Niller.
How to find Nillers
The best way to find these nasty nil pointer problems is to set memory location zero to be an odd number (a good choice is 'NIL!' = $4E494C21, which is numerically odd, as well as personality-wise). Please see OV 15 - Debugging Tips for details on how to do this.
If you use TMON, you can use the extended user area with Discipline. Discipline will set memory location 0 to 'NIL!' to help catch those nasty pointer problems. If you use Macsbug, just type SM 0 'NIL! and go. Realize of course, that if a program has made a transgression and is actually using nil pointers, this may make the program crash with an ID=2 system error. This is good! This means that you have found a bug that may have been causing you untold grief. Once you know where a program crashes, it is usually very easy to use a debugger to find where the error is in the source code. When the program is compiled, turn on the debugging labels (usually a $D+ option). Set memory location 0 to be 'NIL!'. When the program crashes, look at where the program is executing and see what routine it was in (from a disassembly). Go back to that routine in the source code and remove the offending code with a grim smile on your face. Another scurvy bug has been vanquished. The intoxicating smell of victory wafts around your head.
Another way to find problems is to use a debugger to do a checksum on the first four bytes in memory (from 0 to 3 inclusive). If the program ever traps into the debugger claiming that the memory changed, see which part of the program altered memory location 0. Any code that writes to memory location zero is guilty of high treason against the state and must be removed. Remember to say, “bugs are not my friends.”
Creating or Using Fake Handles
A fake handle is one that was not manufactured by the system, but was created by the program itself. An example of a fake handle is:
CONST aMem = $100;
VAR myHandle: Handle;
myPointer: Ptr;
myPointer := Ptr (aMem); { the address of some memory }
myHandle := @myPointer; {the address of the pointer variable. Very bad.}
The normal way to create and use handles is to call the Memory Manager NewHandle function.
Why it’s Bad
A handle that is manufactured by the program is not a legitimate handle as far as the operating system is concerned. Passing a fake handle to routines that use handles is a good way to discover the meaning of “Death by ROM.” For example, think how confused the operating system would get if the fake handle were passed to DisposHandle. What would it dispose? It never allocated the memory, so how can it release it? Programs that manufacture handles may find that the operating system is no longer their friend.
When handles are passed to various ROM routines, there is no telling what sorts of things will be done to the handle. There are any number of normal handle manipulation calls that the ROM may use, such as SetHandleSize, HLock, HNoPurge, MoveHHi and so on. Since a program cannot guarantee that the ROM will not be doing things like this to handles that the program passes in, it is wise to make sure that a real handle is being used, so that all these type of operations will work as the ROM expects. For fake handles, the calls like HLock and SetHandleSize have no bearing. Fake handles are very easy to create, and they are very bad for the health of otherwise upstanding programs. Whenever you need a handle, get one from the Memory Manager.
As a particularly bad use of a fake handle:
VAR myHandle: Handle;
myStuff: myRecord;
myHandle := NewHandle (SIZEOF(myStuff)); { create a new normal handle }
myHandle^ := @myStuff; {YOW! Intended to make myHandle a handle to
the myStuff record. What it really does is
blow up a Master Pointer block, Heap corruption,
and death by Bad Heap. Never do this. }
This can be a little confusing, since it is fine to use your own pointers, but very bad to use your own handles. The difference is that handles can move in memory, and pointers cannot, hence the pointers are not dangerous. This does not mean you should use pointers for everything since that causes other problems. It merely means that you have to be careful how you use the handles.
The use of fake handles usually causes system errors, but can be somewhat mysterious in its effects. Fake handles can be particularly hard to track down since they often cause damage that is not uncovered for many minutes of use. Any use of fake handles that causes the heap to be altered will usually crash the system. Heap corruption is a common failure mode. In clinical studies, 9 out of 10 programmers recommend uncorrupted heaps to their users who use heaps.
How to avoid being a fakir
The correct way to make a handle to some data is to make a copy of the data:
IF errCode <> noErr THEN ErrorHandler ('Out of memory');
Always, always, let the Memory Manager perform operations with handles. Never write code that assigns something to a master pointer, like:
VAR myDeath: Handle;
myDeath^ := stuff; { Don’t change the Master pointer. }
If there is code like this, it usually means the heap is being corrupted, or a fake handle is being used. It is, however, OK to pass around the handle itself, like:
myCopyHandle := myHandle; { perfectly OK, nobody will yell about this. }
This is far different than using the ^ operator to accidentally modify things in the system. Whenever it is necessary to write code to use handles, be careful. Watch things carefully as they are being written. It is much easier to be careful on the way in than it is to try to find out why something is crashing. Be very careful of the @ operator. This operator can unleash untold problems upon unsuspecting programs. If at all possible, try to avoid using it, but if it is necessary, be absolutely sure you know what it is doing. It is particularly dangerous since it turns off the normal type checking that can help you find errors (in Pascal). In short, don’t get crazy with pointer and handle manipulations, and they won’t get crazy with you.
How to find fakirs
Problems of this form are particularly insidious because it can be very difficult to find them after they have been created. They tend to not crash immediately, but rather to crash sometime long after the real damage has been done. The best way to find these problems is to run the program with Discipline. (Discipline is a programmer’s tool that will check all parameters passed to the ROM to see if they are legitimate. Discipline can be found as a stand-alone tool, but the most up-to-date version will be found in the Extended User Area for the TMON debugger. The User Area is public domain, but TMON itself is not. TMON has a number of other useful features, and is well worth the price.) Discipline will check handles that are passed to the ROM to see if they are real handles or not, and if not, will stop the program at the offending call. This can lead you back to the source at a point that may be close to where the bad handle was created. If a program passes the Discipline test, it will be a healthy, robust program with drastically improved odds for compatibility. Programs that do not pass Discipline can sleep poorly at night, knowing that they have broken at least one or two of the “rules.”
A way to find programs that are damaging the heap is to use a debugger (TMON or Macsbug) and turn on the Heap Check operation. This will check the heap for errors at each trap call, and if the heap is corrupted will break into the debugger. Hopefully this will be close to where the code is that caused the damage. Unfortunately, it may not be close enough; this will force you to look further back.
Looking in the source code, look for all uses of the @ operator, and examine the code carefully to see if it is breaking the rules. If it is, change it to step in line with the rest of the happy programs here in happy valley. Also, look for any code that changes a master pointer like the myHandle^ := stuff. Any code of this form is highly suspect, and probably a member of the Anti-Productivity League. The APL has been accused of preventing software sales and the rise of the Yen. These problems can be quite difficult to find at times, but don’t give up. These fake handles are high on the list of guilty parties, and should never be trusted.
Writing code that modifies itself
Self-modifying code is software that changes itself. Code that alters itself runs into two main groupings: code that modifies the code itself and code that changes the block the code is stored in. Copy protection code often modifies the code itself, to change the way it operates (concealing the meaning of what the code does). Changing the code itself is very tricky, and also prone to having problems, particularly when the microprocessor itself changes. There are third-party upgrades available that add a 68020 to a Macintosh. Because of the 68020’s cache, programs that modify themselves stand a good chance of having problems when run on a 68020. This is a compatibility point that should not be missed (nudge, nudge, wink, wink). Code that changes other code (or itself) is prone to be incompatible when the microprocessor changes.
The second group is code that changes the block that the code is stored in. Keeping variables in the CODE segment itself is an example of this. This is uncommon with high-level languages, but it is easy to do in assembly language (using the DC directive). Variables defined in the code itself should be read-only (constants). Code that modifies itself has signed a tacit agreement that says “I’m being tricky, if I die, I’ll revise it.”
Why it’s Bad
There are now three different versions of the microprocessor, the 68000, 68010, and the 68020. They are intended to be compatible with each other, but may not be compatible with code that modifies itself. As the Macintosh evolves, the system may have compatibility problems with programs that try to “push the envelope.”
How to avoid being an abuser
Well, the obvious answer is to avoid writing self-modifying code. If you feel obliged to write self-modifying code, then you are taking an oath to not complain when you break in the future. But don’t worry about accidentally taking the oath: you won’t do it without knowing it. If you choose to abuse, you also agree to personal visits from the Apple thought police, who will be hired as soon as we find out.
How to find abusers
Run the program on a 68020 system. If it fails, it could be related to this problem, but since there are other bugs that might cause failures, it is not guaranteed to be a self-modifying code problem. Self-modifying code is often used in copy protection, which brings us to the next big topic.
Code designed strictly as copy protection
Copy protection is used to make it difficult to make copies of a program. The basic premise is to make it impossible to copy a program with the Finder. This will not be a discussion as to the pros and cons of copy protection. Everyone has an opinion. This will be a description of reality, as it relates to compatibility.
Why it’s Bad
System changes will never be made merely to cause copy protection schemes to fail, but given the choice between improving the system and making a copy protection scheme remain compatible, the system improvement will always be chosen.
• Copy protection is number one on the list of why programs fail the compatibility test.
• Copy protection by its very nature tends to do the most “illegal” things.
• Programs that are copy protected are assumed to have signed a tacit agreement to revise the program when the system changes.
Copy protection itself is not necessarily bad. What is bad is when programs that would otherwise be fully compatible do not work due only to the copy protection. This is very sad, since it requires extra work, revisions to the software, and time lost while the revision is being produced. The users are not generally humored when they can no longer use their programs. Copy protection schemes that fail generally cause system errors when they are run. They also can refuse to run when they should.
How to avoid being a protectionist
The simple answer is to do without copy protection altogether. If you think of compatibility as a probability game, if you leave out the copy protection, your odds of winning skyrocket. As noted above, copy protection is the single biggest reason why programs fail on the various versions of the Macintosh. For those who are required to use copy protection, try to rely on schemes that do not require specific hardware and make sure that the scheme used is not performing illegal operations. If a program runs, an experienced Macintosh programmer armed with a debugger can probably make a copy of it, (no matter how sophisticated the copy protection scheme) so a moderate scheme that does not break the rules is probably a better compatibility bet. The trickier and more devious the scheme, the higher the chance of breaking a rule. Tread lightly.
How to find protectionists
The easiest way to see if a scheme is being overly tricky is to run it on a Macintosh XL. Since the floppy disk hardware is different this will usually demonstrate an unwanted hardware dependency. Be wary of schemes that don’t allow installation on a hard disk. If the program cannot be installed on a hard disk, it may be relying upon things that are prone to change. Don’t use schemes that access the hardware directly. All Macintosh software should go through the various managers in the ROM to maintain compatibility. Any code that sidesteps the ROM will be viewed as having said “It’s OK to make me revise myself.”
Check errors returned as function results
All of the Operating System functions, as well as some of the Toolbox functions, will return result codes as the value of the function. Don’t ignore these result codes. If a program ignores the result codes, it is possible to have any number of bad things happen to the program. The result code is there to tell the program that something went wrong; if the program ignores the fact that something is wrong, that program will probably be killed by whatever went wrong. (Bugs do not like to be ignored.) If a program checks errors, an anomaly can be nipped in the bud, before something really bizarre happens.
Why it’s Bad
A program that ignores result codes is skipping valuable information. This information can often prevent a program from crashing and keep it from losing data.
How to avoid becoming a skipper
Always write code that is defensive. Assume that everyone and everything is out to kill you. Trust no one. An example of error checking is:
myRezzie := GetResource (myResType, myResId);
IF myRezzie = nil THEN ErrorHandler ('Who stole my resource...');
IF fsErrCode <> noErr THEN ErrorHandler (fsErrCode, 'File error');
And another:
myTPPrPort := PrOpenDoc (myTHPrint, nil, nil);
IF PRError <> noErr THEN ErrorHandler (PRError, 'Printing error');
Any use of Operating System functions should presume that something nasty can happen, and have code to handle the nasty situations. Printing calls, File Manager calls, Resource Manager calls, and Memory Manager calls are all examples of Operating System functions that should be watched for returning errors. Always, always check the result codes from Memory Manager calls. Big memory machines are pretty common now, and it is easy to get cavalier about memory, but realize that someone will always want to run the program under Switcher, or on smaller Macintoshes. It never hurts to check, and always hurts to ignore it.
How to find skippers
This is easy: just do weird things while the program is running. Put in locked or unformatted disks while the program is running. Use unconventional command sequences. Run out of disk space. Run on 128K Macintoshes to see how the program deals with running out of memory. Run under Switcher for the same reason. (Programs that die while running under Switcher are often not Switcher’s fault, and are in fact due
to faulty memory management.) Print with no printer connected to the Macintosh. Pop disks out of the drives with the Command-Shift sequence, and see if the program can deal with no disk. When a disk-switch dialog comes up, press Command-period to pass back an error to the requesting program (128K ROMs only). Torturing otherwise well- behaved programs can be quite enjoyable, and a number of users enjoy torturing the program as much as the program enjoys torturing them. For the truly malicious, run the debugger and alter error codes as they come back from various routines. Sure it’s a dirty low-down rotten thing to do to a program, but we want to see how far we can push the program. (This is also a good way to check your error handling.) It’s one thing to be an optimist, but it’s quite another to assume that nothing will go wrong while a program is running.
Accessing hardware directly
Sometimes it is necessary to go directly to the Macintosh hardware to accomplish a specific task for which there is no ROM support. Early hard disks that used the serial ports had no ROM support. Those disks needed to use the SCC chip (the 8530 communication chip) in a high-speed clocked fashion. Although it is a valid function, it is not something that is supported in the ROM. It was therefore necessary to go play with the SCC chip directly, setting and testing various hardware registers in the chip itself. Another example of a valid function that has no ROM support is the use of the alternate video page for page-flipping animation. Since there is no ROM call to flip pages, it is necessary to go play with the right bit in the VIA chip (6522 Versatile Interface Adapter). Going directly to the hardware does not automatically throw a program into the incompatible group, but it certainly lowers its odds.
Why it’s bad
Going directly to the hardware poses any number of problems for enlightened programs that are trying to maintain compatibility across the various versions of the Macintosh. On the Macintosh XL for example, a lot of the hardware is found in different locations, and in some cases the hardware doesn’t exist. On the XL there is no sound chip. Programs that go directly to the sound hardware will find they don’t work correctly on an XL. If the same program were to go through the Sound Manager, it would work fine, although the sound would not be the same as expected. Since the Macintosh is heavily oriented to the software side of things, expecting various hardware to always be available is not a safe bet. Choosy programmers choose to leave the hardware to the ROM.
How to avoid having a hard attack
Don’t read or write the hardware. Exhaust every possible conventional approach before deciding to really get down and dirty. If there is a Manager in the ROM for the operation you wish to perform, it is far better to use the Manager than to go directly to the hardware. Compatibility at the hardware level can very rarely be maintained, but compatibility at the Manager level is a prime consideration. If a program is down to the last ditch effort, and cannot get the support from the ROM that is desired, then access the hardware in an enlightened approach. The really bad way to do it:
VIA := Pointer ($EFE1FE); { sure it’s the base address today…}
{ This is bad. Hard-coded number. }
The with-it, inspired programmer of the eighties does something like:
TYPE LongPointer = ^LongInt;
VAR VIA: LongPointer;
VIABase: LongInt;
VIA := Pointer ($1D4); { the address of the low-memory global. }
VIABase := VIA^; { get the low-memory variable’s value }
{ Now VIABase has the address of the chip }
The point here is that the best way to get the address of a hardware chip is to ask the system where it currently is to be found. The system always knows where the pieces of the system are, and will always know for every incarnation of the Macintosh. There are low-memory global variables for all of the pieces of hardware currently found in the Macintosh. This includes the VIA, the SCC, the Sound Chip, the IWM, and the video display. Whenever you are stuck with going to the hardware, use the low-memory globals. The fact that a program goes directly to the hardware means that it is risking imminent incompatibility, but using the low-memory global will ensure that the program has the best odds. It’s like going to Las Vegas: if you don’t gamble at all, you don’t lose any money; if you have to gamble, play the game that you lose the least on.
How to find hard attacks
Run the suspicious program on the Macintosh XL. Nearly all of the hardware is in a different memory location on the XL. If a program has a hard-coded hardware address in it, it will fail. It may crash, or it might not perform the desired task, but it won’t work as advertised. This unfortunately, is not a completely legitimate test, since the XL does not have some of the hardware of other Macintoshes, and some of the hardware that is there has the register mapping different. This means that it is possible to play by the rule of using the low-memory global and still be incompatible.
Don’t use bits that are reserved
Occasionally during the life of a Macintosh programmer, there comes a time when it is necessary to bite the bullet and use a low-memory global. These are very sad days, since it has been demonstrated (by history) that low-memory global variables are a mysterious lot, and not altogether friendly. One fellow in particular is known as ROM85, a word located at $28E. This particular variable has been documented as the way to determine if a program is running on the 128K ROMs or not. Notably, the top most bit of that word is the determining bit. This means that the rest of the bits in that word are reserved, since nothing is described about any further bits. Remember, if it doesn’t say, assume it’s reserved. If it’s reserved, don’t depend upon it. Take the cautious way out and assume that the other bits that aren’t documented are used for Switcher local variables, or something equally wild. An example of a bad way to do the comparison is:
VAR Rom85Ptr: WordPtr;
RomsAre64: Boolean;
Rom85Ptr := Pointer ($28E); { point at the low-memory global }
IF Rom85Ptr^ = $7FFF THEN RomsAre64 := False { Bad test. }
ELSE RomsAre64 := True;
This is a bad test since the comparison is testing the value of all of the bits, not only the one that is valid. Since the other bits are undocumented, it is impossible to know what they are used for. Assume they are used for something that is arbitrarily random, and take the safe way out.
How to avoid being bitten
VAR ROM85Ptr: Ptr
Rom85Ptr := Pointer ($28E); { point at the low-memory global }
IF BitTst(ROM85Ptr,0) THEN RomsAre64 := True {Good--tests only hi-bit}
ELSE RomsAre64 := False;
This technique will ensure that when those bits are documented, your program won’t be using them for the wrong things. Beware of trojan bits.
Don’t use undocumented stuff. Be very careful when you use anything out of the ordinary stream of a high-level language. For instance, in the ROM85 case, it is very easy to make the mistake of checking for an absolute value instead of testing the actual bit that encodes the information. Whenever a program is using low-memory globals, be sure that only the information desired is being used, and not some undocumented (and hence reserved) bits. It’s not always easy to determine what is reserved and what isn’t, so conservative programmers always use as little as possible. Be wary of the strange bits, and accept rides from none of them. The ride you take might cause you to revise your program.
How to find those bitten
Since there are such a multitude of possible places to get killed, there is no simple way to see what programs are using illegal bits. As time goes by it will be possible to find more of these cases by running on various versions of the Macintosh, but there will probably never be a comprehensive way of finding out who is accepting strange rides, and who is not. Whenever the use of a bit changes from reserved status to active, it will be possible to find those bugs via extensive testing. From a source level, it would be advisable to look over any use of low-memory globals, and eye them closely for inappropriate bit usage. Do a global search for the $ (which describes those ubiquitous hexadecimal numbers), and when found see if the use of the number is appropriate. Trust no one that is not known. If they are documented, they will stay where they are, and have the same meaning. Be very careful in realms that are undocumented. Bits that suddenly jump from reserved to active status have been known to cause more than one program to have a sudden anxiety attack. It is very unnerving to watch a program go from calm and reassuring to rabid status. Users have been known to drop their keyboards in sudden shock (which is bad on the keyboards).
Summary
So what does all this mean? It means that it is getting harder and harder to get away with minor bugs in programs. The minor bugs of yesterday are the major ones of today. No one will yell at you for having bugs in your program, since all programs have bugs of one form or another. The goal should be to make the programs run as smoothly and effortlessly as possible. The end-users will never object to bug-reduced programs.
What is the best way to test a program? A reasonably comprehensive test is to exercise all of the program’s functions under the following situations:
• Use Discipline to be sure the program does not pass illegal things to the ROM.
• Use heap scramble and heap purge to be sure that handles are being used correctly, and that the memory management of the program is correct.
• Run with a checksum on memory locations 0...3 to see if the program writes to these locations.
• Run on a 128K Macintosh, or under Switcher with a small partition, to see how the program deals with memory-critical situations.
• Run on a 68020 system to see if the program is 68020-compatible and to make sure that changing system speed won’t confuse the program.
• Run on a Macintosh XL to be sure that the program does not assume too much about the operating system, and to test screen handling.
• Run on an Ultra-Large screen to be sure that the screen handling is correct, and that there are no hard-coded screen dimensions.
• Run on 64K ROM machines to be sure new traps are not being used when they don’t exist.
• Run under both HFS and MFS to be sure that the program deals with the file system correctly. (400K floppies are usually MFS.)
If a program can live through all of this with no Discipline traps, no checksum breaks, no system errors, no anomalies, no data loss and still get useful work done, then you deserve a gold medal for programming excellence. Maybe even an extra medal for conduct above and beyond the call of duty. In any case, you will know that you have done your job about as well as it can be done, with today’s version of the rules, and today’s programming tools.
Sounds like a foreboding task, doesn’t it? The engineers in Macintosh Technical Support are available to help you with compatibility issues (we won’t always be able to talk about new products, since we love our jobs, but we can give you some hints about compatibility with what the future holds).
Good luck.
Further Reference:
• Technical Note OV 3 - Compatibility Guidlines
• Technical Note OV 15 - Debugging Tips
$ HR ˇ ˇˇˇˇ R H † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
HR . ° d ONLN d ç Z †} ( õ Z OV 4 - Compatibility: Why & How
° d ONLN d ü Z Æ ö *Overview
° d ONLN d * ∫ Z Δ í * Revised by: ° d ONLN d 7 ∫„ Δ ( √„
March 1988 ° d ONLN d B Δ Z “ è ( œ Z Written by: ° d ONLN d N Δ ¢ “ · )H Bob Johnson ° d ONLN d Z Δ÷ “ ( œ÷
° d ONLN dwΔ Z“7 *'Don’t assume the screen is a fixed size ° d ONLN dü“ Zfi ¬ * To get the screen size: ° d ONLN d∏fl ~Î
+$
• check the QuickDraw global ,
Courier ° d ONLN d’fi
ÍÑ )èscreenBits.bounds ° d ONLN dÁ˜ Z] ( Z.Don’t assume the screen is in a fixed location ° d ONLN d Z ’ * To get the screen location: ° d ONLN d3 ~
+$
• check the QuickDraw global ° d ONLN dP
í )èscreenBits.baseAddr ° d ONLN dd) Z5 ƒ (2 ZDon’t assume that ° d ONLN dv( ƒ4 )jrowBytes ° d ONLN d~)5… )@$ is equal to the width of the screen ° d ONLN d£5 ZA (> Z%To get the number of bytes on a line: ° d ONLN d B ~N
+$
• check the QuickDraw global ° d ONLN dÁA
Mí )èscreenBits.rowBytes ° d ONLN d˚N ZZ À (W ZTo get the screen width: ° d ONLN d[ ~g
+$
• check the QuickDraw global ° d ONLN d2Z
fÆ )èscreenBits.bounds.right ° d ONLN dJg Zs Í (p Z To do screen-size calculations: ° d ONLN dkt ~Ä õ +$
• Use ° d ONLN dqs õ ” ) LongInts ° d ONLN dzç Zô ˘ (ñ Z Don’t write to or read from ° d ONLN dñå ˘ò )ünil ° d ONLN dôçôW ) Handles or ° d ONLN d•åWòo )Fnil ° d ONLN d®çoô¢ ) Pointers ¿ X¿
(’ Z OV 4 - Compatibility: Why & How (’ˇ1 ) of 21 (Î ZOverview ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø Ü HR ˇ ˇˇˇˇ R H
HR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d H 6 T ˆ *$ Don’t create or Use Fake Handles ° d ONLN d ! T 6 ` Û * (To avoid creating or using fake handles: ° d ONLN d K ` Z ló +$ ?• Always let the Memory Manager perform operations with handles ° d ONLN d å l Z xz * =• Never write code that assigns something to a master pointer ° d ONLN d Ñ 6 ê ( ç 6%Don’t write code that modifies itself ° d ONLN d ê 6 úm * BSelf modifying code will not live across incarnations of the 68000 ° d ONLN d3 ® 6 ¥ú *?Think carefully about code designed strictly as copy protection ° d ONLN ds ¥ 6 ¿" * 3To avoid copy protection-related incompatibilities: ° d ONLN d® ¿ Z à ˚ +$ "• Avoid copy protection altogether ° d ONLN dà à Z ÿ[ * 6• Rely on schemes that don’t require specific hardware ° d ONLN d ÿ Z ‰s * :• Make sure your scheme doesn’t perform illegal operations ° d ONLN d@ 6 ¸ § ( ˘ 6Don’t ignore errors ° d ONLN dT ¸ 6 ª * To get valuable information: ° d ONLN dr Z +$ &• Check all pertinent calls for errors ° d ONLN dõ Z È * • Always write defensive code ° d ONLN d∫, 68  (5 6 Don’t access hardware directly ° d ONLN dŸ8 6D * ,To avoid hardware-related incompatibilities: ° d ONLN dD ZP ˚ +$ "• Don’t read or write the hardware ° d ONLN d+P Z\‡ * Q• If you can’t get the support from the ROM, ask the system where the hardware is ° d ONLN d~\ Zh Ÿ * • Use low-memory globals ° d ONLN dót 6Ä Ë (} 6 Don’t use bits that are reserved ° d ONLN d∏Ä 6åE * 8To avoid compatibility problems when bit status changes: ° d ONLN dÚå Zò +$ • Don’t use undocumented stuff ° d ONLN dò Z§¨ * A• When using low-memory globals, check only what you want to know ° d ONLN dT∞ 6º k (π 6Summary ° d ONLN d\» 6‘K *:Minor bugs are getting harder and harder to get away with: ° d ONLN dò‘ Z‡ ì +$ • Good luck ° d ONLN d•‡ ZÏ í * • We’ll help ° d ONLN d≥Ï Z¯ * • AppleLink: MacDTS, MCI: MacDTS ° d ONLN d’¯ Zó * >• U.S. Mail: 20525 Mariani Ave.; M/S 27-T; Cupertino, CA 95014
° d ONLN d 6+ x (( 6
What it Is
° d ONLN d 7 6CØ *PThe basic idea is to make sure that your programs will run, regardless of which ° d ONLN do7ØC¯ (@ØMacintosh they ° d ONLN d~C 6Ov (L 6Care being run on. The current systems to be concerned with include: ° d ONLN d√[ Zg ∞ +$• Macintosh 128K ° d ONLN d‘[ Δg! )l• Macintosh 512Ke ° d ONLN dÁg Zs ∞ (p Z• Macintosh 512K ° d ONLN d¯g Δs )l• Macintosh Plus ° d ONLN d
s Z • (| Z• Macintosh XL ° d ONLN ds Δ )l• Macintosh SE ° d ONLN d) Zã ù (à Z• Macintosh II ¿ 4¿˘
(’ 62 ) of 21 (’f OV 4 - Compatibility: Why & How +lOverview ˇ∂ HR ˇ ˇˇˇˇ R H
HR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X /
° d ONLN d < Z H Ì ( E Z If you perform operations in ° d ONLN d < Ì H )ì:a generic fashion, there is rarely any reason to know what ° d ONLN d X H Z Tÿ ( Q ZOmachine is running. This means that you should avoid writing code to determine ° d ONLN d ß Hÿ T ( Qÿ
which version ° d ONLN d µ T Z `ù ( ] ZEof the machine you are running on, unless it is absolutely necessary. ° d ONLN d ˚ l Z x‹ *RFor the purposes of this discussion, the term “programs” will be used to describe ° d ONLN dM l‹ x ( u‹
any code that ° d ONLN d[ x Z Ñ~ ( Å Z8runs on a Macintosh. This includes applications, INITs, ° d ONLN dì x~ Ñ ( Å~FKEYs, Desk Accessories and ° d ONLN dØ Ñ Z ê Å ( ç ZDrivers.
° d ONLN d∏ ® Z ∑ Û *'What the “Rules” mean
° d ONLN dŒ √ Z œ *YCompatibility across all Macintosh computers (which may sound like it involves more work ° d ONLN d' √ œ ( Ãfor ° d ONLN d+ œ Z €@ ( ÿ Z/you) may actually mean that you have less work ° d ONLN dZ œ@ € )Ê.to do, since it may not be necessary to revise ° d ONLN dâ € Z Á û ( ‰ Z
your program ° d ONLN dñ € û Á )DLeach time Apple brings out a new computer or System file. Users, as a group, ° d ONLN d„ Á Z Û∂ ( ZKdo not understand compatibility problems; all they see is that the program ° d ONLN d. Á∂ Û ( ∂does not run on their ° d ONLN dD Û Z ˇ ( ¸ Zsystem. ° d ONLN dL Z` *5The benefits of being compatible are many-fold: your ° d ONLN dÅ ` (`$customers/users stay happy, you have ° d ONLN d¶ Z# ’ ( Zless programming to do, ° d ONLN dæ ’# ){@you can devote your time to more valuable goals, there are fewer ° d ONLN dˇ# Z/ç (, ZBversions to deal with, your code will probably be more efficient, ° d ONLN dA#ç/ (,ç your users will not curse you ° d ONLN d_/ Z;è (8 ZBunder their breath, and your outlook on life will be much merrier. ° d ONLN d¢G ZS0 **Now that we know what being compatible is ° d ONLN dÃG0S )÷1all about, recognize that nobody is requiring you ° d ONLN d˛S Z_ (\ ZXto be compatible with anything. Apple does not employ roving gangs of thought police to ° d ONLN dVS_ (\be ° d ONLN dY_ Zk ƒ (h Zsure that developers ° d ONLN dn_ ƒk )j?are following the recommended guidelines. Furthermore, when the ° d ONLN dÆk Zw& (t Z)guidelines comprise 1200 pages of turgid ° d ONLN d◊k&wI )Ãprose ( ° d ONLN dfikIwú )#Inside Macintosh ° d ONLN dÓkúw )S), you can be expected to ° d ONLN dw ZÉü (Ä ZHmiss one or two of the “rules.” It is no sin to be incompatible, nor is ° d ONLN dPwüÉ (Äüit a punishable offense. If ° d ONLN dlÉ Zè e (å Zit ° d ONLN doÉ eè ) Swere, there would be no Macintosh programs, since virtually all developers would be ° d ONLN d√è Zõh (ò Z7incarcerated. What it does mean, however, is that your ° d ONLN d˙èhõ (òh"program will be unfavorably viewed ° d ONLN d õ Zß Œ (§ Z until it steps in line with ° d ONLN d9õ Œß )tCthe current system (which is a moving target). If a program becomes ° d ONLN d}ß Z≥∑ (∞ ZFincompatible with a new Macintosh, it usually requires rethinking the ° d ONLN d√ß∑≥ (∞∑offending code, and ° d ONLN d◊≥ ZøY (º Z0releasing a new version. You may read something ° d ONLN d≥Yø )ˇ&like “If the developers followed Apple ° d ONLN d.ø ZÀ (» Z%guidelines, they would be compatible ° d ONLN dSøÀ )∏5with the transverse-hinged diatomic quark realignment ° d ONLN dâÀ Z◊ç (‘ Z@system.” This means that if you made any mistakes (you read all ° d ONLN d…Àç◊ (‘ç 1200 pages carefully, right?), ° d ONLN dË◊ Z„D (‡ Z,you will not be compatible. It is extremely ° d ONLN d ◊D„ )Í*difficult to remain completely compatible, ° d ONLN d ?„ ZÔ≠ (Ï ZHparticularly in a system as complex as the Macintosh. The rules haven’t ° d ONLN d á„≠Ô (Ï≠changed, but what you ° d ONLN d ùÔ Z˚î (¯ Z>can get away with has. There are, however, a number of things ° d ONLN d €Ôî˚ (¯îthat you can do to improve ° d ONLN d ˆ˚ ZJ ( Z/your odds—some of which will be explained here. ° d ONLN d
& Z ¥ *It’s your choice ° d ONLN d
7+ Z7 É * It is still ° d ONLN d
C+ É7 ))Syour choice whether you will be concerned with compatibility or not. Apple will not ° d ONLN d
ó7 ZCJ (@ Z3put out a warrant for your arrest. However, if you ° d ONLN d
7JC )/are doing things that are specifically illegal, ° d ONLN d
˙C ZOn (L Z8Apple will also not worry about “breaking” your program. ° d ONLN d 3[ Zg õ *
Bad Things ° d ONLN d >s Z *&The following list is not intended to ° d ONLN d ds )´7be comprehensive, but these are the primary reasons why ° d ONLN d ú Zã“ (à ZIprograms break from one version of the system to the next. These are the ° d ONLN d “ã (à“current top ten ° d ONLN d ıã Zó ß (î Z
commandments: ° d ONLN d £ ZØ ^ *I ° d ONLN d £ ~Øa )$1Thou shalt not assume the screen is a fixed size. ¿ X¿
(’ Z OV 4 - Compatibility: Why & How (’ˇ3 ) of 21 (Î ZOverview ˇ¶ HR ˇ ˇˇˇˇ R H
HR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d < 6 H > *II ° d ONLN d < Z H[ )$8Thou shalt not assume the screen is at a fixed location. ° d ONLN d < I 6 U B ( R 6III ° d ONLN d @ I Z U € )$Thou shalt not assume that ,
Courier ° d ONLN d [ H € T )ÅrowBytes ° d ONLN d c I U∏ )8% is equal to the width of the screen. ° d ONLN d â V 6 b B ( _ 6IV ° d ONLN d å V Z b ¥ )$Thou shalt not use ° d ONLN d ü U ¥ a … )Znil ° d ONLN d ¢ V … b ) handles or ° d ONLN d Æ U a )7nil ° d ONLN d ± V bB )
pointers. ° d ONLN d º b 6 n > ( k 6V ° d ONLN d æ b Z n )$*Thou shalt not create or use fake handles. ° d ONLN d È n 6 z B ( w 6VI ° d ONLN d Ï n Z z0 )$/Thou shalt not write code that modifies itself. ° d ONLN d z 6 Ü F ( É 6VII ° d ONLN d z Z ܶ )$GThou shalt think twice about code designed strictly as copy protection. ° d ONLN dh Ü 6 í J ( è 6VIII ° d ONLN dm Ü Z íP )$5Thou shalt check errors returned as function results. ° d ONLN d£ í 6 û C ( õ 6IX ° d ONLN d¶ í Z û )$(Thou shalt not access hardware directly. ° d ONLN dœ û 6 ™ ? ( ß 6X ° d ONLN d— û Z ™ƒ )$MThou shalt not use any of the bits that are reserved (unused means reserved). ° d ONLN d ∂ 6 ¬¶ ( ø 6MThis has been determined from extensive testing of our diverse software base. ° d ONLN dm Œ 6 ⁄ ˛ *#Assuming the screen is a fixed size ° d ONLN dë Ê 6 Ú" *1Do not assume that the Macintosh screen is 512 x ° d ONLN d¬ Ê" Ú¯ )Ï+342 pixels. Programs that do generally have ° d ONLN dÓ Ú 6 ˛ Ê ( ˚ 6"problems on (or special case for) ° d ONLN d Ú Ê ˛¯ )∞0the Macintosh XL, which has a wider screen. Most ° d ONLN dA ˛ 6
t ( 6Bapplications have to create the bounding rectangle where a window ° d ONLN dÉ ˛t
é Ãö¯ )ñ:example, the screen size is 760x364 (and sometimes 608x431 ° d ONLN dHö 6¶ (£ 6,with alternate hardware). If a program uses ° d ONLN dtö¶¯ )‰(the hard-coded 0,0,342,512 as a bounding ° d ONLN dù¶ 6≤‚ (Ø 6\rectangle, end users will not be able to move their windows past the fictitious boundary of ° d ONLN d˘¶‚≤¯ (Ø‚512. ° d ONLN d˛≥ 6ø È (º 6&If something similar were done to the ° d ONLN d$≤ Èæ/ )≥
GrowWindow ° d ONLN d.≥/øfl )F' call, it would make it impossible for ° d ONLN dU≥flø¯ )∞users ° d ONLN d[ø 6ÀÆ (» 6Mto grow their window to fill the entire screen. (Always a saddening waste of ° d ONLN d®øÆÀ¯ (»Ævaluable screen ° d ONLN d∏À 6◊ m (‘ 6
in a dynamic ° d ONLN d n[ xg¯ )BLfashion. Programs should read the appropriate variables while the program is ° d ONLN d ªg 6s ˝ (p 6+running (at run-time, not at compile time). ° d ONLN d Á 6ã: *4Here’s how smart programs get the screen dimensions:
° d ONLN d
ó Z¢« +$IInitGraf(@thePort); { QuickDraw global variables have to be initialized.}
° d ONLN d
h° Z≠ ` * … ¿ 4¿˘ (’ 64 ) of 21 (’f OV 4 - Compatibility: Why & How +lOverview ˇÙ HR ˇ ˇˇˇˇ R H
HR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X / ,
Courier
° d ONLN d < ~ G‹ ( D ~FboundsRect := screenBits.bounds; { The Real way to get screen size } , Helvetica ° d ONLN d I F ¢ Q Ú +$
( ° d ONLN d s F2 Q6 )ê ° d ONLN d u F6 Q‡ )"{ Use QuickDraw global variable. }
° d ONLN d ò \ Z h r ( e ZThis ° d ONLN d ù \ r h )Vis smart, because the program never has to know specifically what the numbers are. All ° d ONLN d Ù h Z t¡ ( q ZNreferences to rectangles that need to be related to the screen (like the drag ° d ONLN dB h¡ t ( q¡and grow areas of ° d ONLN dT u Z Å √ ( ~ Zwindows) should use ° d ONLN dh t √ Ä: )iscreenBits.bounds ° d ONLN dy u: Å˙ )w) to avoid worrying about the screen size. ° d ONLN d£ ç Z ôú ( ñ ZFNote that this does not do anything remotely like assume that “if the ° d ONLN dÈ çú ô ( ñúcomputer is not a standard ° d ONLN d ô Z •ÿ ( ¢ ZNMacintosh, then it must be an XL.” Special casing for the various versions of ° d ONLN dR ôÿ • ( ¢ÿ
the Macintosh ° d ONLN d` • Z ±π ( Æ ZHhas always been suspicious at best; it is now grounds for breaking. (At ° d ONLN d® •π ± ( Æπleast with respect to ° d ONLN dæ ± Z Ω π ( ∫ Zscreen dimensions.) ° d ONLN d“ … Z ’' **By the way, remember to take into account ° d ONLN d¸ …' ’ )Õ1the menu bar height when using this rectangle. On ° d ONLN d. ÷ Z ‚y ( fl Z8128K ROMs (and later) you can use the low-memory global ° d ONLN df ’y ·ø ( fly
mBarHeight ° d ONLN dp ÷ø ‚¬ )F ° d ONLN dq ÷¬ ‚¯ ) (a word at ° d ONLN d| ’¯ · )6$BAA ° d ONLN dÄ ÷ ‚ ) ). ° d ONLN dÉ ‚ Z Ó ‡ ( Î Z But since we didn’t provide ° d ONLN dü ‚ ‡ Ó )Ü<a low-memory global for the menu bar height in the 64K ROMs, ° d ONLN d‹ Ô Z ˚ ˇ ( ¯ Z#you’ll have to hard code it to 20 ( ° d ONLN dˇ Ó ˇ ˙ )•$14 ° d ONLN d Ô ˚Œ )'). (You’re not the only ones to forget ° d ONLN d) ÔŒ ˚ )∫the future holds ° d ONLN d: ˚ Z à ( Z changes.) ° d ONLN dD Z x *1How to find fascist screenism in current programs ° d ONLN dv+ Z7 *$The easiest way is to exercise your ° d ONLN dö+7 )Æ5program on one of the Ultra-Large screen Macintoshes. ° d ONLN d–7 ZC∑ (@ ZIThere should be no restrictions on sizing or moving the windows, and all ° d ONLN d7∑C (@∑drawing should have ° d ONLN d-C ZO> (L Z/no problems. If there are any anomalies in the ° d ONLN d\C>O )‰,program’s usage, there is probably a lurking ° d ONLN dâO Z[ ¥ (X Zproblem. Also, do ° d ONLN dõO ¥[ )ZJa global find in the source code to see if the numbers 512 or 342 occur in ° d ONLN dÊ[ Zg¥ (d ZLthe program. If so, and if they are in reference to the screen, excise them. ° d ONLN d3s ZG **Assuming the screen is at a fixed location ° d ONLN d^ã Zó* **Some programs use a fixed screen address, ° d ONLN dàã*ó )–2assuming that the screen location will be the same ° d ONLN dªó Z£ († ZXon various incarnations of the Macintosh. This is not the case. For example, the screen ° d ONLN dó£ (†is ° d ONLN d§ Z∞ € (≠ Zlocated at memory location ° d ONLN d1£ €Ø )Å$1A700 ° d ONLN d7§∞u )* on a 128K Macintosh, ° d ONLN dM§u∞Å )pat ° d ONLN dP£ÅØ´ ) $7A700 ° d ONLN dV§´∞ )* on a 512K Macintosh, ° d ONLN dl± ZΩ e (∫ Zat ° d ONLN do∞ eº è ) $F8000 ° d ONLN du± èΩ )* on the Macintosh XL, and at ° d ONLN dí∞ ºF )ç$FA700 ° d ONLN dò±FΩ∂ )* on the Macintosh Plus. ° d ONLN d∞… Z’ • (“ Z Why it’s Bad ° d ONLN dΩ· ZÌ *\When a program relies upon the screen being in a fixed location, Murphy’s Law dictates that ° d ONLN d·Ì (Ían ° d ONLN d Ì Z˘˙ (ˆ ZYunknowing user will run it upon a computer with the screen in a different location. This ° d ONLN duÌ˙˘ (ˆ˙usually ° d ONLN d}˘ Z ( Z[causes the system to crash, since the offending program will write to memory that was used ° d ONLN dÿ˘ (for ° d ONLN d‹ Z‘ ( ZLsomething important. Programs that crash have been proven to be less useful ° d ONLN d (‘ (‘than those that ° d ONLN d 8 Z w ( Zdon’t. ° d ONLN d ?) Z5$ *"How to avoid being a base screener ° d ONLN d bA ZM Ô *#Suffice it to say that there is no ° d ONLN d ÖA ÔM )ï@way that the address of the screen will remain static, but there ° d ONLN d ΔM ZYò (V Z?are rare occasions where it is necessary to go directly to the ° d ONLN d
MòY (Vòscreen memory. On these ° d ONLN d
Y Ze≠ (b ZFoccasions, there are bad ways and not-as-bad ways to do it. A bad way:
° d ONLN d < Z Gê +$>myScreenBase := screenBits.baseAddr; { Good. Always works. } ° d ONLN d A F ~ Q ‚ +$
° d ONLN d V F Í QÀ )l- {Yet another QuickDraw global variable}
° d ONLN d Ñ \ 6 hè ( e 6HUsing the latter approach is guaranteed to work, since QuickDraw has to ° d ONLN d à \è h¯ ( eèknow where to draw, ° d ONLN d ‡ h 6 t ( q 6/and the operating system tells QuickDraw where ° d ONLN d h t¯ )Á+the screen can be found. When in doubt, ask ° d ONLN d; t 6 Ä” ( } 6SQuickDraw. This will work on Macintosh computers from now until forever, so if you ° d ONLN dé t” į ( }”use this ° d ONLN dó Ä 6 åË ( â 6Wapproach you won’t have to revise your program just because the screen moved in memory. ° d ONLN dÔ ò 6 §µ *NIf you have a program (such as an INIT) that cannot rely upon QuickDraw being ° d ONLN d= òµ §¯ ( °µinitialized (via ° d ONLN dN § 6 ∞ n ( Æ 6InitGraf ° d ONLN dV • n ± ® )8), then it is ° d ONLN dd • ® ±
):possible to use the ° d ONLN dx §
∞B )bScrnBase ° d ONLN dÄ •B ±¯ )8# low-memory global variable (a long ° d ONLN d§ ≤ 6 æ _ ( ª 6word at ° d ONLN d¨ ± _ Ω { ))$824 ° d ONLN d∞ ≤ { æ ‡ ) ). This method runs ° d ONLN dƒ ≤ ‡ æ¯ )e6a distant second to asking QuickDraw, but is sometimes ° d ONLN d˚ æ 6 h ( « 6
necessary. ° d ONLN d ÷ 6 ‚ — *How to find base screeners ° d ONLN d! Ó 6 ˙ ê *The easiest way to ° d ONLN d4 Ó ê ˙¯ )ZIfind base screeners is to run the offending program on machines that have ° d ONLN d~ ˙ 6 Ç ( 6different screen ° d ONLN dè ˙ ǯ )LLaddresses. If any addresses are being used in a base manner, the system will ° d ONLN d‹ 6À ( 6Pusually crash. The offending program may also occasionally refuse to draw. Some ° d ONLN d,À¯ (Àprograms ° d ONLN d5 6 ¸ ( 6*afflicted with this problem may also hang ° d ONLN d_ ¸ ¯ )Δ0the computer (sometimes known as accessing funny ° d ONLN dê 6+ ó (( 6space). Also, do a ° d ONLN d£ ó+æ )a8global find on the source code to look for numbers like ° d ONLN d€ æ*Ë ((æ$7A700 ° d ONLN d· Ë+¯ )* or ° d ONLN dÂ+ 67 ` (5 6$1A700 ° d ONLN dÎ, `8ñ )*B. When found, exercise caution while altering the offending lines. ° d ONLN d.F 6RÑ (O 6:Assuming that rowbytes is equal to the width of the screen ° d ONLN di_ 6k à *!According to the definition of a ° d ONLN dä^ Ãj ˆ )ñbitMap ° d ONLN dê_ ˆk$ )*
found in ° d ONLN dö_$ku ).Inside Macintosh ° d ONLN d™_uk™ )Q (p I-144), ° d ONLN d∂_™k¯ )5you can see that ° d ONLN d«k 6w n (u 6rowBytes ° d ONLN dœl nx | )8 is ° d ONLN d”l |x )Dthe number of actual bytes in memory that are used to determine the ° d ONLN dk wÙ (u bitMap ° d ONLN d lÙx¯ )*. ° d ONLN d x 6Ñ3 (Å 61We know the screen is just a big hunk of memory, ° d ONLN dPx3ѯ )˝$and we know that QuickDraw uses that ° d ONLN duÖ 6ë u (é 6 memory as a ° d ONLN dÅÑ uê ü )?bitMap ° d ONLN dáÖ üë ¶ )*. ° d ONLN dâÑ ¶ê fi )rowBytes ° d ONLN dëÖ fiëu )8! accomplishes the translation of ° d ONLN d≤Öuë¯ )óa big hunk of memory into ° d ONLN dÃí 6û > (õ 6a ° d ONLN dŒë >ù h )bitMap ° d ONLN d‘í hû ¶ )*. To do this, ° d ONLN d‚ë ¶ù fi )>rowBytes ° d ONLN dÍí fiû · )8 ° d ONLN dÎí ·û¯ )7tells the system how long a given row is in memory and, ° d ONLN d#û 6™: (ß 6/more importantly, where in memory the next row ° d ONLN dRû:™¯ (ß:%starts. For conventional Macintoshes, ° d ONLN dx™ 6∂ n (¥ 6rowBytes ° d ONLN dÄ´ n∑ ¡ )8 (bytes per Row) ° d ONLN dëÆ ¡∫ « +S* ° d ONLN dí´ «∑» (¥ «9 8 (Pixels per Byte) gives the final horizontal width of ° d ONLN dÀ´»∑¯ (¥»
the screen ° d ONLN d÷π 6≈J (¬ 6<as Pixels per Row. This does not have to be the case. It is ° d ONLN dπJ≈¯ (¬J#possible to have a Macintosh screen ° d ONLN d6Δ 6“ g (œ 6
where the ° d ONLN d@≈ g— ü )1rowBytes ° d ONLN dHΔ ü“; )8! extends beyond what is actually ° d ONLN diΔ;“¯ )ú'visible on the screen. You can think of ° d ONLN dë” 6fl (‹ 6/it as having the screen looking in on a larger ° d ONLN d¿“ fi3 )”bitMap ° d ONLN dΔ”3flÊ )*'. Diagrammatically, it might look like: ¿ 4¿˘
(’ 66 ) of 21 (’f OV 4 - Compatibility: Why & How +lOverview ˇ˙ HR ˇ ˇˇˇˇ R H
HR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X / † Ç † å
< Ωπ
4 L Ú∑ 8 ° ñ ° ö ˇ˛ † ò ,
Courier
À ¸ À ¸ ° d ONLN dˇˇ ( ≈ BaseAddr: † ô † ó ° ñ ° ö ˇ˛ - † ò ° d ONLN dˇˇ ( G(Big Hunk o’ Memory † ô † ó
@Ä 4 µ Úg 8 ° ñ 2 Â
L ° ö ˇ˛ † ò ° d ONLN dˇˇ ( Ì
Visible Area † ô † ó ° ñ 2 ∞ ˝ ª] ° ö ˇ˛ * † ò ° d ONLN dˇˇ ( ∏screenBits.Bounds † ô † ó † ¨ a d≠ x¡ ˆ 0 a d È x ˝ B 0 n ˙ nÆ † ≠ ° ñ 2 h; si ° ö ˇ˛ † ò ° d ONLN dˇˇ ( p>RowBytes † ô † ó † ç † É
° d ONLN dú¶ ~±» +$BbytesLine := screenBits.bounds.right DIV 8; { bad use of bounds } ¿ X¿
(’ Z OV 4 - Compatibility: Why & How (’ˇ7 ) of 21 (Î ZOverview ˇ
HR ˇ ˇˇˇˇ R H
HR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d < Z G ˇ +$!rightSide := screenBits.rowBytes ° d ONLN d ! ? ˇ J +•* ° d ONLN d " < GÆ ( D" 8; { bad use of rowBytes }
° d ONLN d E U 6 a Ú ( ^ 6(will find that the screen may have more ° d ONLN d m T Ú `* )ºrowBytes ° d ONLN d u U* aD )8 than ° d ONLN d { UD a¯ )$previously thought. The best way to ° d ONLN d † a 6 m« ( j 6Wavoid being a row byter is to use the proper variables for the proper things. Without ° d ONLN d ˜ a« m¯ ( j«
the proper ° d ONLN d m 6 y‚ ( v 6[mathematical basis to the screen, life becomes much more difficult. Always do things like:
° d ONLN d_ Ö Z êÆ +$DbytesLine := screenBits.rowBytes; { always the correct number } ° d ONLN d• è Z ö« *
IrightSide := screenBits.bounds.right; { always the correct screen size }
° d ONLN dÔ • 6 ± « ( Æ 6 It is sometimes necessary to ° d ONLN d • « ±¯ )ë<do calculations involving the screen. If so, be sure to use ° d ONLN dI ± 6 Ω n ( ª 6LongInts ° d ONLN dQ ≤ n æ ¯ )8 for all the math, and be sure ° d ONLN dp ≤ ¯ æü )ä%to use the right variables (i.e. use ° d ONLN dï ±ü Ω◊ )ßLongInts ° d ONLN dù ≤◊ æ¯ )8). For ° d ONLN d• ¿ 6 Ã" ( … 62example, if we need to find the address of the 500 ° d ONLN d◊ Ω" …+ ( Δ"th ° d ONLN dŸ ¿+ Ãı + , row in the screen (500 lines from the top):
° d ONLN d ÿ 6 „ E ( ‡ 6VAR ° d ONLN d
ÿ Z „ å )$
myAddress: ° d ONLN d ÿ ¢ „ )HLongInt; ° d ONLN d ‚ Z Ì x ( Í ZmyRow: ° d ONLN d& ‚ ~ Ì ¶ )$LongInt; ° d ONLN d0 ‚ Í Ì≤ )l({ so the calculations don’t round off. } ° d ONLN dZ Ï Z ˜ á ( Ù Z myOffset: ° d ONLN dd Ï ¢ ˜ )HLongInt; ° d ONLN dm Ï Í ˜î )H"{ could easily be over 32768 ... } ° d ONLN dë ˆ Z å ( ˛ Z
bytesLine: ° d ONLN dú ˆ ¢ )HLongInt; ° d ONLN d¶ Z Ω ( ZGmyAddress := ord4(screenBits.baseAddr);{start w/the real base address } ° d ONLN dÔ
Z ™ *
myRow := 500; ° d ONLN d
Æ )¥ {the row we want to address } ° d ONLN d$ Z ü ( ZAbytesLine := screenBits.rowBytes; {the real bytes per line } ° d ONLN dg Z) *
"myOffset := myRow * bytesLine; ° d ONLN dä )€ )¥) {lines * bytes per lines gives bytes } ° d ONLN dµ* Z5 (2 Z"myAddress := myAddress + myOffset; ° d ONLN dÿ*5ö )¥ {final address of the 500 ° d ONLN dÙ'ö2§ (/öth ° d ONLN dˆ*§5« +
line }
° d ONLN d˛@ 6L ¥ (I 6This is not something you ° d ONLN d@ ¥L¯ )~Bwant to do if you can possibly avoid it, but if you simply must go ° d ONLN d[L 6X › (U 6%directly to the screen, be careful. ° d ONLN dÄL ›X¯ )ß8The big-screen machines (Ultra-Large screens) will thank ° d ONLN dπX 6de (a 6:you for it. If QuickDraw cannot be initialized, there is ° d ONLN dÛXed¯ (aealso the low-memory global ° d ONLN dd 6p u (n 6 screenRow ° d ONLN de uq ´ )? (a word at ° d ONLN d#d ´p « )6$106 ° d ONLN d'e «qX ) !) that will give you the current ° d ONLN dHdXpê )ërowBytes ° d ONLN dPeêqî )8. ° d ONLN dT} 6â º (Ü 6How to find row byters ° d ONLN dkï 6° G *To ° d ONLN dnï G°¯ )Rfind current problems with row byter programs, run them on a machine equipped with ° d ONLN d¡° 6≠$ (™ 62Ultra-Large screens and see if any anomalies crop ° d ONLN dÛ°$≠¯ )Ó*up. Look for drawing sequences that don’t ° d ONLN d ≠ 6π7 (∂ 67work right, and for drawing that clips to an imaginary ° d ONLN dU≠7π¯ (∂7(edge. For source-level inspection, look ° d ONLN d~∫ 6Δ _ (√ 6 for uses ° d ONLN dá∫ _Δ ))of the ° d ONLN déπ ≈ ∑ ) rowBytes ° d ONLN dñ∫ ∑Δ¯ )8C variables and be sure that they are being used in a mathematically ° d ONLN d⁄« 6” É (– 6sound fashion. ° d ONLN dÍ« É”W )M+Be highly suspicious of any code that uses ° d ONLN dΔW“è )‘rowBytes ° d ONLN d «è”¯ )8 for the screen width. ° d ONLN d5” 6fl ¸ (‹ 6(Any calculations involving those system ° d ONLN d]” ¸fl¯ )Δ3variables should be closely inspected for round-off ° d ONLN dëfl 6ÎA (Ë 6:errors and improper use. Search for the number 8. If it ° d ONLN dÀflAί (ËA'is being used in a calculation where it ° d ONLN dÛÎ 6˜ ≤ (Ù 6is the number of bits per ° d ONLN d
Î ≤˜¯ )|Bbyte, then watch that code closely for improper conceptualization. ° d ONLN d Q˜ 6∏ ( 6TThis is code that could leap out and grab you by the throat at anytime. Be careful! ° d ONLN d ® 6( \ *%Using ° d ONLN d Æ \' t )&nil ° d ONLN d ± t( ∫ ) Handles or ° d ONLN d Ω ∫' “ )Fnil ° d ONLN d ¿ “( ) Pointers ° d ONLN d 5 6A A (> 6A ° d ONLN d Ã4 A@ V ) nil ° d ONLN d œ5 VA „ )! pointer is a pointer that has a ° d ONLN d 5 „A¯ )ç9value of 0. Recognize that pointers are merely addresses ° d ONLN d
*B 6N œ (K 6 in memory. This means that a ° d ONLN d
HA œM ‰ )ônil ° d ONLN d
KB ‰N¯ )6 pointer is pointing to memory location 0. Any use of ° d ONLN d
ÇN 6Zó (W 6Imemory location 0 is strictly forbidden, since it is owned by Motorola. ° d ONLN d
ÀNóZ¯ (WóTrespassers may be ° d ONLN d
fiZ 6f- (c 66shot on sight, but they may not die until much later. ° d ONLN d Z-f¯ )˜' Sometimes trespassers are only wounded ° d ONLN d <f 6r ¶ (o 6and act strangely. Any ° d ONLN d Tf ¶r¯ )pDuse of memory location 0 can be considered a bug, since there are no ° d ONLN d ôs 6 { (| 6valid reasons ° d ONLN d ßs {„ )EBfor Macintosh programs to read or write to that memory. However, ° d ONLN d Èr„~¯ (|„nil ° d ONLN d ÌÄ 6å (â 6-pointers themselves are not necessarily bad. ° d ONLN d Äåπ )“& It is occasionally necessary to pass ° d ONLN d @π㌠)±nil ° d ONLN d CÄŒå¯ ) pointers ° d ONLN d Må 6ò Í (ï 6%to ROM routines. This should not be ° d ONLN d rå Íò¯ )¥6confused with reading or writing to memory location 0. ° d ONLN d ™ò 6§e (° 6BA pointer normally points to (contains the address of) a location ° d ONLN d Ïòe§¯ (°e in memory. It could look like ° d ONLN d
§ 6∞ J (≠ 6this: ¿ 4¿˘
*(8 ) of 21 (’f OV 4 - Compatibility: Why & How +lOverview ˇ¬ HR ˇ ˇˇˇˇ R H
HR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X / † Ç † å ° ñ ° ö * R † ò
H u ,
Courier
Ãã Ãã ° d ONLN dˇˇ ( UYThis is how a Pointer
† ô ° ö R † ò ° d ONLN dˇˇ * works. The address of
† ô ° ö R † ò ° d ONLN dˇˇ * the pointer variable itself
† ô ° ö R † ò ° d ONLN dˇˇ * is $E9310 (@P) and is four
† ô ° ö ˇ˛ R † ò ° d ONLN dˇˇ * bytes long. The pointer points
† ô ° ö ˇÛ R † ò ° d ONLN dˇˇ * to (contains the address of)
† ô ° ö ˇË R † ò ° d ONLN dˇˇ * the block at $3E4DE (P).
† ô ° ö ˇ› R † ò ° d ONLN dˇˇ * That memory location is where
† ô ° ö ˇ“ R † ò ° d ONLN dˇˇ * the actual data resides (P^). † ô † ó
4 K ” 8
™U™U™U™U 4 › ” 8 ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( õMemory 0 † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( ù Ç
Higher Memory † ô † ó ° ñ ° ö ˇ˛ ! † ò ° d ONLN dˇˇ ( T }Highest Memory † ô † ó
4 ` ” l 8 ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ +l$3E4DE † ô † ó
† ò ° d ONLN dˇˇ * Data † ô † ó " e ) " »E ù † ™ a ∫ ÿ0 B 0 " »EÁ † ≠ ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( h °
P: $E9310: † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( ú P^: $3E4DE: † ô † ó † ç † É
HR
° d ONLN d ! Z- Ì (* Z!If a pointer has been cleared to ° d ONLN d ! Ì, )ìnil ° d ONLN d $!-≠ )&, it will point to memory location 0. ° d ONLN d J!≠- )´ This is OK as long as ° d ONLN d a. Z: k (7 Zthe ° d ONLN d e. k:‚ )Mprogram does not try to read from or write to that pointer. An example of a ° d ONLN d ≤-‚9˜ (7‚nil ° d ONLN d µ.˜: ) pointer ° d ONLN d æ: ZF £ (C Zcould look like: † Ç † å
R u)
4U ” 8
™U™U™U™U 4Á ” 8 ° ñ ° ö † ò
◊ã ◊ã ° d ONLN dˇˇ +K’ Memory 0 † ô ° ö ˇ¯ ˇ˚ † ò ° d ONLN dˇˇ + (P^) † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ (ß Ç
Higher Memory † ô † ó ° ñ ° ö ˇ˛ ! † ò ° d ONLN dˇˇ (^ }Highest Memory † ô † ó
4j ”v 8 ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ +x0 † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ (‘ ∞$3E4DE: † ô † ó
Ä 4≥ ”ÿ 8 ° ñ 2π Óƒ ° ö
† ò ° d ONLN dˇˇ (¡ ÛReal
† ô 2ƒ Óœ ° ö ˇ¯
† ò ° d ONLN dˇˇ * Data † ô † ó "o ) EoE † ™ a&2 B 0 "EÈ † ≠ ° ñ ° ö $ J † ò ° d ONLN dˇˇ (ehThis is a nil Pointer.
† ô ° ö J † ò ° d ONLN dˇˇ * Note that the memory that
† ô ° ö J † ò ° d ONLN dˇˇ * it points to (the address)
† ô ° ö J † ò ° d ONLN dˇˇ * is 0 (P^). This is wrong.
† ô ° ö ˇ¯ J † ò ° d ONLN dˇˇ * There is no valid data at
† ô ° ö ˇÌ J † ò ° d ONLN dˇˇ * memory location 0. Any † ô ° ö ˇ‚ J † ò ° d ONLN dˇˇ * writing to or reading from † ô ° ö ˇ◊ J † ò ° d ONLN dˇˇ * this pointer is a bug. † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ (r °
P: $E9310: † ô † ó † ç † É
HR
° d ONLN d œ5 ZAfi (> ZRnil handles are related to the problem, since a handle is merely the address of a ° d ONLN d!5fiA (>fi
pointer (or a ° d ONLN d/A ZMΔ (J ZNpointer to a pointer). An example of what a normal handle might look like is: ¿ X¿
*ã OV 4 - Compatibility: Why & How (’ˇ9 ) of 21 (Î ZOverview ˇΔ HR ˇ ˇˇˇˇ R H
HR , Times
. +6-Macintosh Technical Notes / 4 /˘ † Ç † å
< ;Û
4 ? ô ‚ 8
™U™U™U™U 4 — ô ˆ ‚ 8
4 ÿ ô ‰ ‚ 8 ° ñ ° ö ˇ˛ † ò ,
Courier
Ã∏ Ã∏ ° d ONLN dˇˇ ++’Memory 0 † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( ë H
Higher Memory † ô † ó ° ñ ° ö ˇ˛ ! † ò ° d ONLN dˇˇ ( H CHighest Memory † ô † ó 4 T ô ` ‚ 8 ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ +l$2603C † ô † ó
Ä 4 ù ô ¬ ‚ 8 ° ñ 2 £ ∞ Æ Œ ° ö
† ò ° d ONLN dˇˇ +OReal
† ô 2 Æ ∞ π Œ ° ö ˇ¯
† ò ° d ONLN dˇˇ * Data † ô † ó " Y ‚; › [ † ™ a œ Ú Ì B 0 " › † ≠ " fi · " Ω ˘ ! † ™ a Ø ’ Õ Û B 0 " Ω ˜¯ † ≠ ° ñ ° ö @ ^ † ò ° d ONLN dˇˇ ( J3 This is how a Handle works.
† ô ° ö 5 ^ † ò ° d ONLN dˇˇ * The address of the handle
† ô ° ö * ^ † ò ° d ONLN dˇˇ * variable itself (H) is $E9310.
† ô ° ö ^ † ò ° d ONLN dˇˇ * That variable points (has the
† ô ° ö ^ † ò ° d ONLN dˇˇ * address) to the master pointer
† ô ° ö ^ † ò ° d ONLN dˇˇ * at location $2603C (H). That
† ô ° ö ˇ˛ ^ † ò ° d ONLN dˇˇ * variable is a pointer also, and
† ô ° ö ˇÛ ^ † ò ° d ONLN dˇˇ * points to the real data found
† ô ° ö ˇË ^ † ò ° d ONLN dˇˇ * !at $3E4DE (H^^). The dark grey
† ô ° ö ˇ› ^ † ò ° d ONLN dˇˇ * "block is a Master pointer block. I ° d ONLN dˇˇ )™t
† ô ° ö ˇ“ ^ † ò ° d ONLN dˇˇ ( ∏3"is a group (usually 64) of Master
† ô ° ö ˇ« ^ † ò ° d ONLN dˇˇ * "Pointers. One of them is the Mast ° d ONLN dˇˇ )™er
† ô ° ö ˇº ^ † ò ° d ONLN dˇˇ ( Œ3 Pointer at address $2603C (H^). † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( ‡ Æ$3E4DE † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( \ g
H: $E9310: † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( æ ] H^^: $3E4DE: † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ +" H^: $2603C: † ô † ó † ç † É † Ç † å ° ñ ° ö $ a † ò
9ÍÙ ÷ª ÷ª ° d ONLN dˇˇ +ÕBThis is a nil Handle.
† ô ° ö a † ò ° d ONLN dˇˇ * Note that the Handle usually
† ô ° ö a † ò ° d ONLN dˇˇ * points to a Master Pointer, but
† ô ° ö a † ò ° d ONLN dˇˇ * in this case it points at (has
† ô ° ö ˇ¯ a † ò ° d ONLN dˇˇ * "the value of) 0 (H^). This is wro ° d ONLN dˇˇ )™ng.
† ô ° ö ˇÌ a † ò ° d ONLN dˇˇ (Y/!Using what is at memory location
† ô ° ö ˇ‚ a † ò ° d ONLN dˇˇ * !0 as a pointer is invalid, since
† ô ° ö ˇ◊ a † ò ° d ONLN dˇˇ * "it is not known what will be there ° d ONLN dˇˇ )™. † ô † ó "Ÿ fl † ™ aë>Ø\ ˆ 0 "ü2 † ≠ ° ñ ° ö ˇ˛ R † ò ° d ONLN dˇˇ (§M H^^: Points someplace strange... † ô † ó
4 ò› ‡ 8
™U™U™U™U 4® òÕ ‡ 8
4Ø òΩ ‡ 8 ° ñ ° ö † ò ° d ONLN dˇˇ (Ÿ d Memory 0 † ô ° ö ˇ¯ ˇ˚ † ò ° d ONLN dˇˇ + (H^) † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ (h F
Higher Memory † ô † ó ° ñ ° ö ˇ˛ ! † ò ° d ONLN dˇˇ ( AHighest Memory † ô † ó 4+ ò7 ‡ 8 ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ +x0 † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ (ï t$3E4DE: † ô † ó
Ä 4t òô ‡ 8 ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ *"$2603C: † ô † ó ° ñ 2z ∞Ö Œ ° ö
† ò ° d ONLN dˇˇ (Ç µReal
† ô 2Ö ∞ê Œ ° ö ˇ¯
† ò ° d ONLN dˇˇ * Data † ô † ó "0 ‡; Ÿ2 † ™ aÀ ÚÈ B 0 "ŸÒ † ≠ "µ fl "ì ˜ " † ™ aÖ ‘£ Ú B 0 "ì ı˘ † ≠ ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ (∑ ¨$3E4DE † ô † ó "⁄ ¯9Δ ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ (3 e
H: $E9310: † ô † ó † ç † É
HR
° d ONLN d ˆ 6Ê (ˇ 6XIf the memory at 0 contains an odd number (numerically odd), then using it as a pointer ° d ONLN d XˆÊ¯ (ˇÊwill ° d ONLN d ] 6é ( 6Kcause a system error with ID=2. This can be very useful, since that tells ° d ONLN d ®é¯ ( éyou exactly where the ° d ONLN d æ 6À ( 6Sprogram is using this illegal handle, making it easy to fix. Unfortunately, there ° d ONLN dÀ¯ (À are cases ° d ONLN d 6' ’ ($ 6"where it is appropriate to pass a ° d ONLN d= ’& Í )ünil ° d ONLN d@ Í'í )! handle to ROM routines (such as ° d ONLN daí& )®GetScrap ° d ONLN di '¯ )8 ). These ° d ONLN ds( 64 § (1 6cases are rare, and it is ° d ONLN dç( §4 √ )nnever ° d ONLN dí( √4X ) " legal to read from or write to a ° d ONLN d¥'X3m )ïnil ° d ONLN d∑(m4ì ) handle. ° d ONLN d¿@ 6LT (I 6<There is also the case of an empty handle. An empty handle ° d ONLN d¸@TL¯ (IT#is one where the handle itself (the ° d ONLN d L 6XE (U 6=first pointer) points to a valid place in memory; that place ° d ONLN d]LEX¯ (UE&in memory is also a pointer, and if it ° d ONLN dÑY 6e A (b 6is ° d ONLN dáX Ad V ) nil ° d ONLN däY Ve ¥ ) the entire handle is ° d ONLN d†Y ¥e¯ )^Btermed empty. There are occasions where it is necessary to use the ° d ONLN d„f 6r • (o 6handle itself, but using ° d ONLN d¸f •r ∑ )othe ° d ONLN d e ∑q à )nil ° d ONLN df Ãr¯ )? pointer that it contains is not valid. An example of an empty ° d ONLN dCr 6~ É ({ 6handle could be: ¿ 4¿˘
*Z10 )
of 21 (’f OV 4 - Compatibility: Why & How +lOverview ˇä HR ˇ ˇˇˇˇ R H
HR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X / † Ç † å ° ñ ° ö / T † ò
< d ,
Courier
ÿÆ ÿÆ ° d ONLN dˇˇ ( GfThis is an Empty Handle.
† ô ° ö $ T † ò ° d ONLN dˇˇ * Note that the handle itself
† ô ° ö T † ò ° d ONLN dˇˇ * has a valid Master Pointer
† ô ° ö T † ò ° d ONLN dˇˇ * address in it $2603C (H^). The
† ô ° ö T † ò ° d ONLN dˇˇ * Master Pointer is nil however,
† ô ° ö ˇ¯ T † ò ° d ONLN dˇˇ * !which is the address of location
† ô ° ö ˇÌ T † ò ° d ONLN dˇˇ * !0 in memory. It is wrong to use
† ô ° ö ˇ‚ T † ò ° d ONLN dˇˇ * !the Master Pointer in this case,
† ô ° ö ˇ◊ T † ò ° d ONLN dˇˇ * although there are cases where
† ô ° ö ˇÃ T † ò ° d ONLN dˇˇ * !using the Handle itself is valid. † ô † ó
4 A ¬ 8
™U™U™U™U 4 “ ¬ ˜ 8
4 Ÿ ¬  8 ° ñ ° ö † ò ° d ONLN dˇˇ ( è Memory 0 † ô ° ö ˇ¯ † ò ° d ONLN dˇˇ + (H^^) † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( í q
Higher Memory † ô † ó ° ñ ° ö ˇ˛ ! † ò ° d ONLN dˇˇ ( I lHighest Memory † ô † ó 4 U ¬ a 8
Ä 4 û ¬ √ 8 " Z ; fiF \F † ™ a – Ó= B 0 " fiFÛ † ≠ ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ +wò0 † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( ] ◊$2603C † ô † ó " fi
# # † ™ a Û B 0 #Ù † ≠ ° ñ 2 • ÷ ∞ ˛ ° ö † ò ° d ONLN dˇˇ +PPurged
† ô 2 ∞ ÷ ª ˛ ° ö ˇ¯
† ò ° d ONLN dˇˇ + Data † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( ] ê
H: $E9310: † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ +b$3E4DE: † ô † ó ° ñ ° ö ˇ˛ † ò ° d ONLN dˇˇ ( · ã H^: $2603C: † ô † ó † ç † É
HR
° d ONLN d Z, • () Z Why it’s Bad ° d ONLN d
9 ZE è * The use of ° d ONLN d 8 èD § )5nil ° d ONLN d 9 §EÌ )G pointers can lead to the use of make-believe data. This make-believe ° d ONLN d b9ÌE (BÌ
data often ° d ONLN d mE ZQö (N ZDchanges for different versions of the computer. This changing data ° d ONLN d ±EöQ (Nö makes it difficult to predict ° d ONLN d œR Z^ ” ([ Zwhat will happen when a ° d ONLN d ÁR ”^ )y
° d ONLN dµ ~¿ +$VAR myHandle: TEHandle; ° d ONLN d … ~‘ Œ *myHandle := nil;
° d ONLN d1fl ZΑ (Ë ZPThat’s pretty straightforward, so what’s the problem? If you do something like:
° d ONLN dɘ ~◊ +$EmyHandle^^.viewRect := myRect; { very bad idea with myHandle = nil }
° d ONLN d…
ZD ( Z2memory location zero will be used as a pointer to ° d ONLN d˚
D )Í,give the address of a TextEdit record. What ° d ONLN d( Z%â (" Z@if that memory location points to something in the system heap? ° d ONLN dhâ% ("â What if it points to the sound ° d ONLN dà% Z1 (. Zbuffer? ° d ONLN dê% 1 )%V In cases like these, eight bytes of rectangle data will be written to wherever memory ° d ONLN dÁ1 Z= ¨ (: Zlocation 0 points. ° d ONLN d¸J ZV Ö * Use of a ° d ONLN dI ÖU ö )+nil ° d ONLN dJ öV⁄ )C handle will never be useful. This memory is reserved and used by ° d ONLN dKJ⁄V (S⁄
the 68000 for ° d ONLN dYV ZbÈ (_ ZRvarious interrupt vectors and Valuable Stuff. This Valuable Stuff is composed of ° d ONLN d´VÈb (_È things that ° d ONLN d∑b Zn/ (k Z,you definitely do not want to change. When ° d ONLN d„b/n )’0changed, the 68000 finds out, and decides to get ° d ONLN dn Zz (w ZXback at your program in the most strange and wonderful ways. These strange results can ° d ONLN dlnz (wrange ° d ONLN drz ZÜ (É Z#from a System Error all the way to ° d ONLN dïz Ü )¶<erasing hard disks and destroying files. There really is no ° d ONLN d“Ü Zí „ (è Z limit to the havoc that can be ° d ONLN dÒÜ „í )âAwreaked. This tends to keep the users on the edge of their seat, ° d ONLN d3í Zû“ (õ ZQbut this is not really the desired effect. As noted above, it won’t necessarily ° d ONLN dÑí“û (õ“cause traumatic ° d ONLN dîû Z™‘ (ß ZMresults. A program can be doing naughty things and not get caught. This is ° d ONLN d·û‘™ (ß‘still a bug that ¿ X¿
(’ Z OV 4 - Compatibility: Why & How (’˙11 )
of 21 (Î ZOverview ˇf HR ˇ ˇˇˇˇ R H
HR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d < 6 H *1needs to be fixed, since it is nearly guaranteed ° d ONLN d 1 < H¯ )‹2to give different results on different versions of ° d ONLN d d H 6 Tà ( Q 6Cthe Macintosh. Programs exhibiting schizophrenia have been proven ° d ONLN d ß Hà T¯ ( Qàto be less enjoyable to ° d ONLN d ø T 6 ` J ( ] 6use. ° d ONLN d ƒ l 6 x ’ *How to avoid being a Niller ° d ONLN d ‡ Ñ 6 ê~ *DWhenever a program uses pointers and handles, it should ensure that ° d ONLN d$ Ñ~ ê¯ ( ç~the pointer or handle will ° d ONLN d? ë 6 ù V ( ö 6not be ,
Œ Ñ ⁄¯ )NLback a handle to the resource data. There are any number of places where it ° d ONLN dZ € 6 Á ¡ ( ‰ 6 may be forced to pass back a ° d ONLN dw ⁄ ¡ Ê ÷ )ãnil ° d ONLN dz € ÷ Á@ ) handle. For example:
° d ONLN dí Û Z ˛ ‹ ( ˚ ZVAR myRezzie: MyHandle; ° d ONLN dÆ Z« *ImyRezzie := MyHandle(GetResource(myResType, myResNumber)); { could be ° d ONLN d z (z missing…} ° d ONLN d Z(ã (% Z=IF myRezzie = nil THEN ErrorHandler('We almost got Nilled') ° d ONLN dQ' Z2 *
%ELSE myRezzie^^.myRect := newRect; ° d ONLN dw'22õ )ÿ { We know it is OK }
° d ONLN dç= 6I (F 6)As another example, think of how handles ° d ONLN d∂=I¯ )Ÿ)can be purged from memory in tight memory ° d ONLN d‡I 6Uº (R 6Mconditions. If a block is marked purgeable, the Memory Manager may throw it ° d ONLN d-IºU¯ (Rº away at any ° d ONLN d9U 6aΩ (^ 6Ptime. This creates an empty handle. The defensive programmer will always make ° d ONLN dâUΩa¯ (^Ω
sure that the ° d ONLN dóa 6m ◊ (j 6!handles being used are not empty.
° d ONLN dºy ZÑ ‹ +$VAR myRezzie: myHandle; ° d ONLN dÿç ZòΩ *GmyRezzie := myHandle(GetResource(myResType, myResNumber)); { could be ° d ONLN d#ó ¢¢ƒ +H
#ELSE myRezzie^^.myRect := newRect; ° d ONLN d¬´∂r )¥{ We know it is OK } ° d ONLN dÿµ Z¿ (Ω Z%tempHandle := NewHandle (largeBlock); ° d ONLN d˛µ2¿π )ÿ{might dispose a purgeable ° d ONLN d!ø2 d *
myRezzie} ° d ONLN d-… Z‘Ω (— ZGIF myRezzie^ = nil THEN LoadResource(Handle(myRezzie)); {Re-load empty ° d ONLN dx” ¢fi° +H
3 handle} ° d ONLN d≠› ZË ◊ (Â ZIF ResError = noErr THEN ° d ONLN d…Á ZÚ ˇ *
! myRezzie^^.StatusField := OK; ° d ONLN dÎÁÚ« )¥%{ guaranteed not empty, and actually ° d ONLN dÒ ¢¸ø (˘ ¢9 gets read back in, if necessary }
° d ONLN dM 6 † ( 6Be especially careful ° d ONLN dc †¢ )j0of places where memory is being allocated. The ° d ONLN d좷 (¢ NewHandle ° d ONLN dú·¯ )? and ° d ONLN d° 6 ` ( 6NewPtr ° d ONLN dß `! Ø )* calls will return ° d ONLN d∫ Ø! ∏ )Oa ° d ONLN dº ∏ Õ ) nil ° d ONLN dø Õ!¯ )= handle or pointer if there is not enough memory. If you use ° d ONLN d˝! 6-ú (* 6Nthat handle or pointer without checking, you will be guilty of being a Niller. ° d ONLN d L9 6E ¶ *How to find Nillers ° d ONLN d `R 6^ — *!The best way to find these nasty ° d ONLN d ÅQ —] Ê )õnil ° d ONLN d ÑR Ê^G ) pointer problems is ° d ONLN d ôRG^¯ )a$to set memory location zero to be an ° d ONLN d æ_ 6k K (h 6odd ° d ONLN d ¡_ Kk ˝ )# number (a good choice is 'NIL!' = ° d ONLN d ‰^ ˝j< )≤ $4E494C21 ° d ONLN d Ì_<kΔ )? , which is numerically odd, ° d ONLN d
_Δk¯ )ä
as well as ° d ONLN d
k 6wΔ (t 6Tpersonality-wise). Please see OV 15 - Debugging Tips for details on how to do this. ° d ONLN d
kÉ 6è ¨ *If you use TMON, you ° d ONLN d
ÄÉ ¨è¯ )vDcan use the extended user area with Discipline. Discipline will set ° d ONLN d
≈è 6õ6 (ò 66memory location 0 to 'NIL!' to help catch those nasty ° d ONLN d
˚è6õ¯ (ò6&pointer problems. If you use Macsbug, ° d ONLN d "ú 6® a (• 6
of 21 (’f OV 4 - Compatibility: Why & How +lOverview ˇ– HR ˇ ˇˇˇˇ R H
HR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X /
° d ONLN d < Z H û ( E Zerror. This is ° d ONLN d < û H )DJgood! This means that you have found a bug that may have been causing you ° d ONLN d [ H Z Tz ( Q Z6untold grief. Once you know where a program crashes, ° d ONLN d ë Hz T ( Qz it is usually very easy to use a ° d ONLN d ≤ T Z `Δ ( ] ZMdebugger to find where the error is in the source code. When the program is ° d ONLN d ˇ TΔ ` ( ]Δcompiled, turn on ° d ONLN d ` Z l ( i Z$the debugging labels (usually a $D+ ° d ONLN d5 ` l )≠7option). Set memory location 0 to be 'NIL!'. When the ° d ONLN dm l Z x¯ ( u ZWprogram crashes, look at where the program is executing and see what routine it was in ° d ONLN dƒ l¯ x ( u¯(from a ° d ONLN dà x Z Ñ˛ ( Å ZXdisassembly). Go back to that routine in the source code and remove the offending code ° d ONLN d$ x˛ Ñ ( Å˛with a ° d ONLN d+ Ñ Z êH ( ç Z1grim smile on your face. Another scurvy bug has ° d ONLN d\ ÑH ê )Ó+been vanquished. The intoxicating smell of ° d ONLN dà ê Z ú Ú ( ô Z victory wafts around your head. ° d ONLN d® ® Z ¥L *2Another way to find problems is to use a debugger ° d ONLN d⁄ ®L ¥ )Ú+to do a checksum on the first four bytes in ° d ONLN d ¥ Z ¿ ¯ ( Ω Z!memory (from 0 to 3 inclusive). ° d ONLN d' ¥ ¯ ¿ )û=If the program ever traps into the debugger claiming that the ° d ONLN de ¿ Z Ãm ( … Z6memory changed, see which part of the program altered ° d ONLN dõ ¿m à ( …m!memory location 0. Any code that ° d ONLN dΩ Ã Z ÿó ( ’ ZEwrites to memory location zero is guilty of high treason against the ° d ONLN d Ãó ÿ ( ’óstate and must be removed. ° d ONLN d ÿ Z ‰1 ( · Z+Remember to say, “bugs are not my friends.” ° d ONLN dJ ¸ Z *$ Creating or Using Fake Handles ° d ONLN di Z ñ *BA fake handle is one that was not manufactured by the system, but ° d ONLN d´ñ ( ñwas created by the program ° d ONLN dΔ Z, () Z(itself. An example of a fake handle is: ,
Courier
° d ONLN d8 ~C ó +$CONST ° d ONLN dˆ8 ¢C fi )$ aMem = $100; ° d ONLN dB ~M ç (J ~VAR ° d ONLN dB ¢M ˜ )$myHandle: Handle; ° d ONLN d L ¢W Ì *
myPointer: Ptr; ° d ONLN d-b ~m ˆ (j ~myPointer := Ptr (aMem); ° d ONLN dFbm§ )ê { the address of some memory } ° d ONLN dfl ~w Ò (t ~myHandle := @myPointer; ° d ONLN d~lw˛ )ê0{the address of the pointer variable. Very bad.}
° d ONLN dØÉ Zè q (å ZThe ° d ONLN d≥É qè› )Cnormal way to create and use handles is to call the Memory Manager ° d ONLN dˆÇ›é (å› NewHandle ° d ONLN d è Zõ Ö (ò Z function. ° d ONLN d ß Z≥ • * Why it’s Bad ° d ONLN dø ZÀ *%A handle that is manufactured by the ° d ONLN d=ø À )Ø:program is not a legitimate handle as far as the operating ° d ONLN dxÀ Z◊ √ (‘ Zsystem is concerned. ° d ONLN dçÀ √◊ )iD Passing a fake handle to routines that use handles is a good way to ° d ONLN d“◊ Z„F (‡ Z-discover the meaning of “Death by ROM.” For ° d ONLN dˇ◊F„ )Ï)example, think how confused the operating ° d ONLN d)‰ ZM (Ì Z3system would get if the fake handle were passed to ° d ONLN d\„MÔ° )Û DisposHandle ° d ONLN dh‰°« )T. What ° d ONLN dp‰« )&would it dispose? ° d ONLN dÉ Z¸[ (˘ Z5It never allocated the memory, so how can it release ° d ONLN d∏[¸ (˘[&it? Programs that manufacture handles ° d ONLN dfl¸ Zr ( Z=may find that the operating system is no longer their friend. ° d ONLN d Z Ñ *=When handles are passed to various ROM routines, there is no ° d ONLN dZÑ ( Ñ!telling what sorts of things will ° d ONLN d| Z, () ZZbe done to the handle. There are any number of normal handle manipulation calls that the ° d ONLN d÷ , ()ROM ° d ONLN d⁄- Z9 ≤ (6 Zmay use, such as ° d ONLN dÎ, ≤8
)X
SetHandleSize ° d ONLN d¯-
9 )[, ° d ONLN d˙,88 )HLock ° d ONLN dˇ-89A )#, ° d ONLN d ,A8y ) HNoPurge ° d ONLN d -y9Ç )8, ° d ONLN d ,Ç8≥ ) MoveHHi ° d ONLN d -≥9 )1 and so on. Since a ° d ONLN d '9 ZE¡ (B ZIprogram cannot guarantee that the ROM will not be doing things like this ° d ONLN d p9¡E (B¡to handles that the ° d ONLN d ÑE ZQ» (N ZPprogram passes in, it is wise to make sure that a real handle is being used, so ° d ONLN d ‘E»Q (N»that all these type ° d ONLN d ËR Z^ ù ([ Zof operations ° d ONLN d ˆR ù^„ )C@will work as the ROM expects. For fake handles, the calls like ° d ONLN d
6Q„] ([„HLock ° d ONLN d
;R^ )# and ° d ONLN d
@^ Zj µ (h Z
SetHandleSize ° d ONLN d
M_ µk ∏ )[ ° d ONLN d
N_ ∏k )Ihave no bearing. Fake handles are very easy to create, and they are very ° d ONLN d
òk Zw¯ (t ZRbad for the health of otherwise upstanding programs. Whenever you need a handle, ° d ONLN d
Ík¯w (t¯get one ° d ONLN d
Úw ZÉ › (Ä Zfrom the Memory Manager. ° d ONLN d
è Zõ *+As a particularly bad use of a fake handle:
° d ONLN d :ß ~≤ ˆ +$VAR myHandle: Handle; ¿ X¿
(’ Z OV 4 - Compatibility: Why & How (’˙13 )
of 21 (Î ZOverview ˇ∂ HR ˇ ˇˇˇˇ R H
HR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d < Z G ◊ +$ myStuff: myRecord; ° d ONLN d P Z [« *ImyHandle := NewHandle (SIZEOF(myStuff)); { create a new normal handle } ° d ONLN d f Z Z eÆ *
DmyHandle^ := @myStuff; {YOW! Intended to make myHandle a handle to ° d ONLN d ≠ d ~ oë +$
7 the myStuff record. What it really does is ° d ONLN d Á n ~ y™ *
< blow up a Master Pointer block, Heap corruption, ° d ONLN d& x ~ ÉÇ *
4 and death by Bad Heap. Never do this. }
° d ONLN d[ é 6 ö‚ ( ó 6_This can be a little confusing, since it is fine to use your own pointers, but very bad to use ° d ONLN d∫ é‚ ö¯ ( ó‚your ° d ONLN dø ö 6 ¶ ( £ 6-own handles. The difference is that handles ° d ONLN dÏ ö ¶¯ )”.can move in memory, and pointers cannot, hence ° d ONLN d ¶ 6 ≤7 ( Ø 64the pointers are not dangerous. This does not mean ° d ONLN dO ¶7 ≤¯ ( Ø7&you should use pointers for everything ° d ONLN dv ≤ 6 æt ( ª 6Dsince that causes other problems. It merely means that you have to ° d ONLN d∫ ≤t æ¯ ( ªtbe careful how you use the ° d ONLN d’ æ 6 ^ ( « 6handles. ° d ONLN dfl ÷ 6 ‚ ^ *The use ° d ONLN dÁ ÷ ^ ‚¯ )(Sof fake handles usually causes system errors, but can be somewhat mysterious in its ° d ONLN d; ‚ 6 Óø ( Î 6Ueffects. Fake handles can be particularly hard to track down since they often cause ° d ONLN dê ‚ø Ó¯ ( Îø damage that ° d ONLN dú Ó 6 ˙. ( ˜ 63is not uncovered for many minutes of use. Any use ° d ONLN dœ Ó. ˙¯ )¯*of fake handles that causes the heap to be ° d ONLN d˙ ˙ 6 Æ ( 6altered will usually crash ° d ONLN d ˙ Ư )xCthe system. Heap corruption is a common failure mode. In clinical ° d ONLN dY 6ı ( 6Zstudies, 9 out of 10 programmers recommend uncorrupted heaps to their users who use heaps. ° d ONLN d¥ 6* œ *How to avoid being a fakir ° d ONLN dœ6 6Bû *LThe correct way to make a handle to some data is to make a copy of the data:
° d ONLN d N ZY “ +$VAR myHandle: Handle; ° d ONLN d7X Zc ◊ *
myStuff: myRecord; ° d ONLN dRn ZyÅ *;errCode := PtrToHand (@myStuff, myHandle, SIZEOF(myStuff)); ° d ONLN dèx ZÉ| *
:IF errCode <> noErr THEN ErrorHandler ('Out of memory');
° d ONLN d é 6ö\ (ó 6:Always, always, let the Memory Manager perform operations ° d ONLN dé\ö¯ (ó\ with handles. Never write code ° d ONLN d$ö 6¶ (£ 61that assigns something to a master pointer, like:
° d ONLN dW≤ ZΩ Õ +$VAR myDeath: Handle; ° d ONLN dpº Z«r *
8myDeath^ := stuff; { Don’t change the Master pointer. }
fi 6Í` (Á 6Aused. It is, however, OK to pass around the handle itself, like:
° d ONLN dPˆ ZÃ +$JmyCopyHandle := myHandle; { perfectly OK, nobody will yell about this. }
° d ONLN dõ
6 Á ( 6%This is far different than using the ° d ONLN d¿ Á Ó )±^ ° d ONLN d¡
Ó” )/ operator to accidentally modify things in the ° d ONLN d
”¯ )Âsystem. ° d ONLN d˘ 6%¿ (" 6QWhenever it is necessary to write code to use handles, be careful. Watch things ° d ONLN dJ¿%¯ ("¿ carefully as ° d ONLN dW% 61B (. 6<they are being written. It is much easier to be careful on ° d ONLN dì%B1¯ (.B(the way in than it is to try to find out ° d ONLN dº2 6> ¿ (; 6why something is crashing. ° d ONLN d◊2 ¿>8 )ä Be very careful of the ° d ONLN dÔ18=? )x@ ° d ONLN d2?>¯ )% operator. This operator can unleash ° d ONLN d > 6J= (G 67untold problems upon unsuspecting programs. If at all ° d ONLN d M>=J¯ (G=*possible, try to avoid using it, but if it ° d ONLN d xJ 6V° (S 6Pis necessary, be absolutely sure you know what it is doing. It is particularly ° d ONLN d »J°V¯ (S°dangerous since it ° d ONLN d €V 6bü (_ 6Oturns off the normal type checking that can help you find errors (in Pascal). ° d ONLN d
*Vüb¯ (_üIn short, don’t get ° d ONLN d
>b 6n≤ (k 6Ocrazy with pointer and handle manipulations, and they won’t get crazy with you. ¿ 4¿˘
*j14 )
of 21 (’f OV 4 - Compatibility: Why & How +lOverview ˇÃ HR ˇ ˇˇˇˇ R H
HR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X /
° d ONLN d < Z H ƒ ( E ZHow to find fakirs ° d ONLN d T Z `v *<Problems of this form are particularly insidious because it ° d ONLN d O Tv ` ( ]v"can be very difficult to find them ° d ONLN d r ` Z lR ( i Z6after they have been created. They tend to not crash ° d ONLN d ® `R l )¯)immediately, but rather to crash sometime ° d ONLN d “ l Z x ( u ZYlong after the real damage has been done. The best way to find these problems is to run ° d ONLN d+ l x ( uthe ° d ONLN d/ x Z ÑÈ ( Å ZQprogram with Discipline. (Discipline is a programmer’s tool that will check all ° d ONLN dÄ xÈ Ñ ( ÅÈ
parameters ° d ONLN dã Ñ Z ê; ( ç Z1passed to the ROM to see if they are legitimate. ° d ONLN dº Ñ; ê )·/ Discipline can be found as a stand-alone tool, ° d ONLN dÏ ê Z ú ( ô Z%but the most up-to-date version will ° d ONLN d ê ú )∑/be found in the Extended User Area for the TMON ° d ONLN dA ú Z ®? ( • Z/debugger. The User Area is public domain, but ° d ONLN dp ú? ® )Â)TMON itself is not. TMON has a number of ° d ONLN dö ® Z ¥î ( ± ZAother useful features, and is well worth the price.) Discipline ° d ONLN d€ ®î ¥ ( ±îwill check handles that are ° d ONLN d˜ ¥ Z ¿÷ ( Ω ZTpassed to the ROM to see if they are real handles or not, and if not, will stop the ° d ONLN dK ¥÷ ¿ ( Ω÷program at the ° d ONLN dZ ¿ Z à ˚ ( … Z#offending call. This can lead you ° d ONLN d} ¿ ˚ à )°<back to the source at a point that may be close to where the ° d ONLN d∫ à Z ÿó ( ’ ZBbad handle was created. If a program passes the Discipline test, ° d ONLN d¸ Ãó ÿ ( ’ó it will be a healthy, robust ° d ONLN d ÿ Z ‰ à ( · Zprogram ° d ONLN d! ÿ à ‰ ).Lwith drastically improved odds for compatibility. Programs that do not pass ° d ONLN dn ‰ Z ‹ ( Ì Z Discipline can sleep poorly ° d ONLN dä ‰ ‹ )ÇBat night, knowing that they have broken at least one or two of the ° d ONLN dÕ Z ¸ ( ˘ Z“rules.” ° d ONLN dŸ Z5 *-A way to find programs that are damaging the ° d ONLN d5 )€+heap is to use a debugger (TMON or Macsbug) ° d ONLN d2 Z ( Z^and turn on the Heap Check operation. This will check the heap for errors at each trap call, ° d ONLN dê ( and ° d ONLN dî Z,ä () ZBif the heap is corrupted will break into the debugger. Hopefully ° d ONLN d÷ ä, ()ä this will be close to where the ° d ONLN dˆ, Z8} (5 Z>code is that caused the damage. Unfortunately, it may not be ° d ONLN d4,}8 (5}!close enough; this will force you ° d ONLN dV8 ZD ª (A Zto look further back. ° d ONLN dnQ Z]N *5Looking in the source code, look for all uses of the ,
Courier ° d ONLN d£PN\U )Ù@ ° d ONLN d§QU]X ) ° d ONLN d•QX] )(operator, and examine the code carefully ° d ONLN dŒ] Ziv (f ZAto see if it is breaking the rules. If it is, change it to step ° d ONLN d]vi (fv"in line with the rest of the happy ° d ONLN d2i Zu( (r Z+programs here in happy valley. Also, look ° d ONLN d]i(u )Œ3for any code that changes a master pointer like the ° d ONLN dëu ZÅ ÿ ( ZmyHandle^ := stuff ° d ONLN d£v ÿÇ ˘ )~. Any ° d ONLN d™v ˘Ç )!:code of this form is highly suspect, and probably a member ° d ONLN dÂÇ Zé (ã Z&of the Anti-Productivity League. The ° d ONLN d Çé )¥5APL has been accused of preventing software sales and ° d ONLN dAé Zö ù (ó Zthe rise of the ° d ONLN dQé ùö )CPYen. These problems can be quite difficult to find at times, but don’t give up. ° d ONLN d£ö Z¶Ë (£ ZWThese fake handles are high on the list of guilty parties, and should never be trusted. ° d ONLN d˝≤ Zæ *!Writing code that modifies itself ° d ONLN d Z÷ *%Self-modifying code is software that ° d ONLN d E ÷ )Ø;changes itself. Code that alters itself runs into two main ° d ONLN d Å÷ Z‚Ÿ (fl ZSgroupings: code that modifies the code itself and code that changes the block the ° d ONLN d ‘÷Ÿ‚ (flŸcode is stored ° d ONLN d „‚ ZÓ∏ (Î ZDin. Copy protection code often modifies the code itself, to change ° d ONLN d
'‚∏Ó (Î∏the way it operates ° d ONLN d
;Ó Z˙ œ (˜ Z(concealing the meaning ° d ONLN d
SÓ œ˙ )uEof what the code does). Changing the code itself is very tricky, and ° d ONLN d
ô˙ Z¢ ( ZDalso prone to having problems, particularly when the microprocessor ° d ONLN d
›˙¢ (¢itself changes. There are ° d ONLN d
¯ Z≥ ( ZIthird-party upgrades available that add a 68020 to a Macintosh. Because ° d ONLN d A≥ (≥of the 68020’s cache, ° d ONLN d W Z ( ZPprograms that modify themselves stand a good chance of having problems when run ° d ONLN d ß (on a ° d ONLN d ¨ Z* (' Z68020. ° d ONLN d ≥ * )%T This is a compatibility point that should not be missed (nudge, nudge, wink, wink). ° d ONLN d * Z6 v (3 ZCode ° d ONLN d * v6 ) Wthat changes other code (or itself) is prone to be incompatible when the microprocessor ° d ONLN d f6 ZB Ñ (? Zchanges. ° d ONLN d qN ZZ *&The second group is code that changes ° d ONLN d óNZ )π8the block that the code is stored in. Keeping variables ° d ONLN d –Z Zfc (c Z2in the CODE segment itself is an example of this. ° d ONLN d
Zcf (cc! This is uncommon with high-level ° d ONLN d
$f Zr6 (o Z,languages, but it is easy to do in assembly ° d ONLN d
Pf6r )‹-language (using the DC directive). Variables ° d ONLN d
~r Z~o ({ Z=defined in the code itself should be read-only (constants). ° d ONLN d
ªro~ ({o$Code that modifies itself has signed ° d ONLN d
‡~ Zäî (á ZIa tacit agreement that says “I’m being tricky, if I die, I’ll revise it.” ¿ X¿
*N OV 4 - Compatibility: Why & How (’˙15 )
of 21 (Î ZOverview ˇË HR ˇ ˇˇˇˇ R H
HR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d < 6 H Å * Why it’s Bad ° d ONLN d
T 6 ` **There are now three different versions of ° d ONLN d 7 T `¯ )“-the microprocessor, the 68000, 68010, and the ° d ONLN d e ` 6 l„ ( i 6V68020. They are intended to be compatible with each other, but may not be compatible ° d ONLN d ª `„ l¯ ( i„with ° d ONLN d ¿ l 6 x Q ( u 6code ° d ONLN d ≈ l Q x¯ )Rthat modifies itself. As the Macintosh evolves, the system may have compatibility ° d ONLN d x 6 Ñ@ ( Å 67problems with programs that try to “push the envelope.” ° d ONLN dP ê 6 ú ‡ * How to avoid being an abuser ° d ONLN dm ® 6 ¥q *BWell, the obvious answer is to avoid writing self-modifying code. ° d ONLN dØ ®q ¥¯ ( ±q If you feel obliged to write ° d ONLN dÕ ¥ 6 ¿π ( Ω 6Pself-modifying code, then you are taking an oath to not complain when you break ° d ONLN d ¥π ¿¯ ( Ωπin the future. ° d ONLN d- ¿ 6 û ( … 6TBut don’t worry about accidentally taking the oath: you won’t do it without knowing ° d ONLN dÅ ¿» ï ( …» it. If you ° d ONLN dç à 6 ÿ œ ( ’ 6 choose to abuse, you also agree ° d ONLN d≠ à œ ÿ¯ )ô=to personal visits from the Apple thought police, who will be ° d ONLN dÎ ÿ 6 ‰ ø ( · 6 hired as soon as we find out. ° d ONLN d 6 ¸ ™ *How to find abusers ° d ONLN d 6 ò *Run the program on ° d ONLN d0 ò¯ )bLa 68020 system. If it fails, it could be related to this problem, but since ° d ONLN d} 6 ñ ( 6there are other bugs ° d ONLN dí ñ ¯ )`Kthat might cause failures, it is not guaranteed to be a self-modifying code ° d ONLN dfi 6,È () 6\problem. Self-modifying code is often used in copy protection, which brings us to the next ° d ONLN d: È,¯ ()Èbig ° d ONLN d>, 68 Q (5 6topic. ° d ONLN dED 6P! *)Code designed strictly as copy protection ° d ONLN do\ 6hX *?Copy protection is used to make it difficult to make copies of ° d ONLN dÆ\Xh¯ (eX a program. The basic premise is ° d ONLN dœh 6t g (q 6 to make it ° d ONLN d⁄h gt¯ )1Rimpossible to copy a program with the Finder. This will not be a discussion as to ° d ONLN d-t 6Ä (} 60the pros and cons of copy protection. Everyone ° d ONLN d]t į )Ê.has an opinion. This will be a description of ° d ONLN dåÄ 6å fi (â 6(reality, as it relates to compatibility. ° d ONLN d∑ò 6§ Å * Why it’s Bad ° d ONLN dƒ∞ 6º- *2System changes will never be made merely to cause ° d ONLN dˆ∞-º¯ )˜*copy protection schemes to fail, but given ° d ONLN d!º 6»$ (≈ 6,the choice between improving the system and ° d ONLN dMº$»¯ )Ó&making a copy protection scheme remain ° d ONLN dt» 6‘R (— 69compatible, the system improvement will always be chosen. ° d ONLN dƇ HÏ L +• ° d ONLN d∞‡ UÏ( )
-Copy protection is number one on the list of ° d ONLN d›‡(Ï‘ )”#why programs fail the compatibility ° d ONLN dÏ U¯ i (ı Utest. ° d ONLN d¯ H L ( H• ° d ONLN d ¯ U• )
ICopy protection by its very nature tends to do the most “illegal” things. ° d ONLN dU H L (
H• ° d ONLN dW Uw )
<Programs that are copy protected are assumed to have signed ° d ONLN dìw‘ (
|† Ò¨¯ )ª4copy protection, your odds of winning skyrocket. As ¿ 4¿˘
(’ 616 )
of 21 (’f OV 4 - Compatibility: Why & How +lOverview ˇ HR ˇ ˇˇˇˇ R H
HR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X /
° d ONLN d < Z H ˆ ( E Z noted above, copy protection is ° d ONLN d < ˆ H )ú:the single biggest reason why programs fail on the various ° d ONLN d [ H Z T í ( Q Z versions of ° d ONLN d g H í T )8Qthe Macintosh. For those who are required to use copy protection, try to rely on ° d ONLN d π T Z `è ( ] Z<schemes that do not require specific hardware and make sure ° d ONLN d ı Tè ` ( ]èthat the scheme used is not ° d ONLN d ` Z l µ ( i Zperforming illegal ° d ONLN d$ ` µ l )[Coperations. If a program runs, an experienced Macintosh programmer ° d ONLN dh l Z x- ( u Z*armed with a debugger can probably make a ° d ONLN dí l- x )”1copy of it, (no matter how sophisticated the copy ° d ONLN dƒ x Z Ñ « ( Å Zprotection scheme) so ° d ONLN d⁄ x « Ñ )mDa moderate scheme that does not break the rules is probably a better ° d ONLN d Ñ Z êØ ( ç ZIcompatibility bet. The trickier and more devious the scheme, the higher ° d ONLN dh ÑØ ê ( çØthe chance of breaking ° d ONLN d ê Z ú æ ( ô Za rule. Tread lightly. ° d ONLN dó ® Z ¥ *How to find protectionists ° d ONLN d≤ ¿ Z Ãò *GThe easiest way to see if a scheme is being overly tricky is to run it ° d ONLN d˘ ¿ò à ( …òon a Macintosh XL. Since ° d ONLN d à Z ÿ ( ’ Z&the floppy disk hardware is different ° d ONLN d9 à ÿ )ª2this will usually demonstrate an unwanted hardware ° d ONLN dl ÿ Z ‰/ ( · Z+dependency. Be wary of schemes that don’t ° d ONLN dó ÿ/ ‰ )’2allow installation on a hard disk. If the program ° d ONLN d ‰ Z – ( Ì Zcannot be installed on a ° d ONLN d„ ‰ – )vBhard disk, it may be relying upon things that are prone to change. ° d ONLN d' Z ¸ º ( ˘ ZDon’t use schemes ° d ONLN d9 º ¸ )bDthat access the hardware directly. All Macintosh software should go ° d ONLN d~ ¸ Z ì ( Z through the ° d ONLN dä ¸ ì )9Ovarious managers in the ROM to maintain compatibility. Any code that sidesteps ° d ONLN d⁄ Z√ ( ZIthe ROM will be viewed as having said “It’s OK to make me revise myself.” ° d ONLN d& Z,C *)Check errors returned as function results ° d ONLN dP8 ZD *VAll of the Operating System functions, as well as some of the Toolbox functions, will ° d ONLN d¶8 D (A return ° d ONLN d≠D ZPÕ (M ZSresult codes as the value of the function. Don’t ignore these result codes. If a ° d ONLN d DÕP (MÕprogram ignores ° d ONLN dP Z\ æ (Y Zthe result codes, it is ° d ONLN d(P æ\ )dEpossible to have any number of bad things happen to the program. The ° d ONLN dn\ Zh õ (e Zresult code is ° d ONLN d}\ õh )AOthere to tell the program that something went wrong; if the program ignores the ° d ONLN dÕh Zt› (q ZOfact that something is wrong, that program will probably be killed by whatever ° d ONLN d h›t (q› went wrong. ° d ONLN d)t ZÄ (} Z?(Bugs do not like to be ignored.) If a program checks errors, ° d ONLN dhtÄ (} an anomaly can be nipped in the ° d ONLN dàÄ Zå3 (â Z-bud, before something really bizarre happens. ° d ONLN d∂ò Z§ • * Why it’s Bad ° d ONLN d√∞ Zº *'A program that ignores result codes is ° d ONLN dÍ∞º )Ω4skipping valuable information. This information can ° d ONLN d º Z»ö (≈ ZCoften prevent a program from crashing and keep it from losing data. ° d ONLN de‘ Z‡ ˙ * How to avoid becoming a skipper ° d ONLN dÖÏ Z¯ … *Always write code that ° d ONLN dúÏ …¯ )oFis defensive. Assume that everyone and everything is out to kill you. ° d ONLN d‰¯ Z: ( Z/Trust no one. An example of error checking is: ,
Courier
° d ONLN d ~_ +$-myRezzie := GetResource (myResType, myResId); ° d ONLN d D ~%“ *
DIF myRezzie = nil THEN ErrorHandler ('Who stole my resource...');
° d ONLN d â0 Z< ≠ (9 ZAnother example:
° d ONLN d õH ~Sñ +$8fsErrCode := FSOpen ('MyFile', myVRefNum, myFileRefNum); ° d ONLN d ’R ~]Õ *
CIF fsErrCode <> noErr THEN ErrorHandler (fsErrCode, 'File error');
° d ONLN d
h Zt ó (q Z And another:
° d ONLN d
'Ä ~ãd +$.myTPPrPort := PrOpenDoc (myTHPrint, nil, nil); ° d ONLN d
° d ONLN d < 6 H *-Any use of Operating System functions should ° d ONLN d - < H¯ )‡,presume that something nasty can happen, and ° d ONLN d Z H 6 T? ( Q 6;have code to handle the nasty situations. Printing calls, ° d ONLN d ï H? T¯ ( Q?$File Manager calls, Resource Manager ° d ONLN d ∫ T 6 `Ì ( ] 6[calls, and Memory Manager calls are all examples of Operating System functions that should ° d ONLN d TÌ `¯ ( ]Ìbe ° d ONLN d ` 6 l ` ( i 6watched ° d ONLN d ` ` l¯ )*Pfor returning errors. Always, always check the result codes from Memory Manager ° d ONLN dq l 6 x¥ ( u 6Icalls. Big memory machines are pretty common now, and it is easy to get ° d ONLN d∫ l¥ x¯ ( u¥cavalier about ° d ONLN d… x 6 Ñ ÿ ( Å 6!memory, but realize that someone ° d ONLN dÍ x ÿ ѯ )¢9will always want to run the program under Switcher, or on ° d ONLN d$ Ñ 6 êö ( ç 6Msmaller Macintoshes. It never hurts to check, and always hurts to ignore it. ° d ONLN dt ú 6 ® Ø *How to find skippers ° d ONLN dâ ¥ 6 ¿ Ú *)This is easy: just do weird things while ° d ONLN d≤ ¥ Ú ¿¯ )º5the program is running. Put in locked or unformatted ° d ONLN dË ¿ 6 à ( … 6)disks while the program is running. Use ° d ONLN d ¿ ï )Õ-unconventional command sequences. Run out of ° d ONLN d? à 6 ÿ å ( ’ 6disk space. Run ° d ONLN dP à å ÿ¯ )VDon 128K Macintoshes to see how the program deals with running out of ° d ONLN dï ÿ 6 ‰› ( · 6Smemory. Run under Switcher for the same reason. (Programs that die while running ° d ONLN dË ÿ› ‰¯ ( ·›under ° d ONLN dÓ ‰ 6 I ( Ì 6<Switcher are often not Switcher’s fault, and are in fact due ° d ONLN d+ ¸ 6 9 * ° d ONLN d, ¸ 9¿ )Qto faulty memory management.) Print with no printer connected to the Macintosh. ° d ONLN d} ¸¿¯ (¿ Pop disks ° d ONLN dâ 6 H ( 6out ° d ONLN dç H¯ )Vof the drives with the Command-Shift sequence, and see if the program can deal with no ° d ONLN d‰ 6 Ô ( 6Vdisk. When a disk-switch dialog comes up, press Command-period to pass back an error ° d ONLN d:Ô ¯ ( Ôto ° d ONLN d= 6,
() 6*the requesting program (128K ROMs only). ° d ONLN dg
,¯ )◊.Torturing otherwise well- behaved programs can ° d ONLN dñ, 68X (5 6>be quite enjoyable, and a number of users enjoy torturing the ° d ONLN d‘,X8¯ (5X program as much as the program ° d ONLN dÛ8 6D (A 6 enjoys torturing them. For the ° d ONLN d8 D¯ )î?truly malicious, run the debugger and alter error codes as they ° d ONLN dSD 6P (M 6,come back from various routines. Sure it’s ° d ONLN dDP¯ )–1a dirty low-down rotten thing to do to a program, ° d ONLN d±P 6\V (Y 6;but we want to see how far we can push the program. (This ° d ONLN dÏPV\¯ (YV is also a good way to check your ° d ONLN d
\ 6h Æ (e 6error handling.) It’s one ° d ONLN d(\ Æh¯ )xFthing to be an optimist, but it’s quite another to assume that nothing ° d ONLN doh 6t (q 6)will go wrong while a program is running. ° d ONLN döÄ 6å ÷ *Accessing hardware directly ° d ONLN d∂ò 6§ ˙ *)Sometimes it is necessary to go directly ° d ONLN dflò ˙§¯ )ƒ2to the Macintosh hardware to accomplish a specific ° d ONLN d§ 6∞m (≠ 6?task for which there is no ROM support. Early hard disks that ° d ONLN dQ§m∞¯ (≠m used the serial ports had no ° d ONLN dn∞ 6º S (π 6ROM ° d ONLN dr∞ Sº¯ ) Ssupport. Those disks needed to use the SCC chip (the 8530 communication chip) in a ° d ONLN dΔº 6»ÿ (≈ 6Rhigh-speed clocked fashion. Although it is a valid function, it is not something ° d ONLN d ºÿ»¯ (≈ÿthat is ° d ONLN d » 6‘ v (— 6
supported in ° d ONLN d -» v‘¯ )@Kthe ROM. It was therefore necessary to go play with the SCC chip directly, ° d ONLN d y‘ 6‡3 (› 66setting and testing various hardware registers in the ° d ONLN d Ø‘3‡¯ )˝(chip itself. Another example of a valid ° d ONLN d ÿ‡ 6Ïi (È 6=function that has no ROM support is the use of the alternate ° d ONLN d
‡iϯ (Èi video page for page-flipping ° d ONLN d
2Ï 6¯ß (ı 6Qanimation. Since there is no ROM call to flip pages, it is necessary to go play ° d ONLN d
ÉÏ߯¯ (ıßwith the right bit ° d ONLN d
ñ¯ 6ä ( 6Gin the VIA chip (6522 Versatile Interface Adapter). Going directly to ° d ONLN d
›¯ä¯ (äthe hardware does not ° d ONLN d
Û 6„ (
6\automatically throw a program into the incompatible group, but it certainly lowers its odds. ° d ONLN d P 6( * Why it’s bad ° d ONLN d ]4 6@z *@Going directly to the hardware poses any number of problems for ° d ONLN d ù4z@¯ (=zenlightened programs that ° d ONLN d ∑@ 6LÅ (I 6Dare trying to maintain compatibility across the various versions of ° d ONLN d ˚@ÅL¯ (IÅthe Macintosh. On the ° d ONLN d L 6X é (U 6Macintosh XL for ° d ONLN d #L éX¯ )XKexample, a lot of the hardware is found in different locations, and in some ° d ONLN d oX 6d∞ (a 6Ocases the hardware doesn’t exist. On the XL there is no sound chip. Programs ° d ONLN d æX∞d¯ (a∞that go directly ° d ONLN d œd 6p· (m 6Yto the sound hardware will find they don’t work correctly on an XL. If the same program ° d ONLN d
(d·p¯ (m·were ° d ONLN d
-p 6|⁄ (y 6Rto go through the Sound Manager, it would work fine, although the sound would not ° d ONLN d
p⁄|¯ (y⁄be the ° d ONLN d
Ü| 6à« (Ö 6Psame as expected. Since the Macintosh is heavily oriented to the software side ° d ONLN d
÷|«à¯ (Ö«
of things, ° d ONLN d
·à 6î æ (ë 6expecting various hardware ° d ONLN d
¸à æî¯ )à=to always be available is not a safe bet. Choosy programmers ° d ONLN d:î 6† ¸ (ù 6(choose to leave the hardware to the ROM. ¿ 4¿˘
*818 )
of 21 (’f OV 4 - Compatibility: Why & How +lOverview ˇF HR ˇ ˇˇˇˇ R H
HR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X /
° d ONLN d < Z H ( E Z!How to avoid having a hard attack ° d ONLN d " T Z ` z *Don’t ° d ONLN d ( T z ` ) Pread or write the hardware. Exhaust every possible conventional approach before ° d ONLN d y ` Z l ( i Z+deciding to really get down and dirty. If ° d ONLN d § ` l )¬3there is a Manager in the ROM for the operation you ° d ONLN d ÿ l Z x › ( u Zwish to perform, it is far ° d ONLN d Û l › x )É>better to use the Manager than to go directly to the hardware. ° d ONLN d3 x Z ÑZ ( Å Z4Compatibility at the hardware level can very rarely ° d ONLN dg xZ Ñ ( ÅZ'be maintained, but compatibility at the ° d ONLN dè Ñ Z ê ° ( ç ZManager level ° d ONLN dù Ñ ° ê )GMis a prime consideration. If a program is down to the last ditch effort, and ° d ONLN dÎ ê Z ú — ( ô Zcannot get the support ° d ONLN d ê — ú )w<from the ROM that is desired, then access the hardware in an ° d ONLN d? ú Z ®I ( • Z3enlightened approach. The really bad way to do it: ,
Courier
° d ONLN dt ¥ ~ øπ +$?VIA := Pointer ($EFE1FE); { sure it’s the base address today…} ° d ONLN d∂ æ ¢ …¶ +$
4 { This is bad. Hard-coded number. }
° d ONLN dÎ ‘ Z ‡° ( › ZEThe with-it, inspired programmer of the eighties does something like:
° d ONLN d2 Ï ~ ˜
+$ TYPE LongPointer = ^LongInt; ° d ONLN dP ~
Ï *VAR VIA: LongPointer; ° d ONLN dh ~ Ï *
VIABase: LongInt; ° d ONLN dÄ ~+√ *AVIA := Pointer ($1D4); { the address of the low-memory global. } ° d ONLN d√* ~5π *
?VIABase := VIA^; { get the low-memory variable’s value } ° d ONLN d4 ¢?Œ +$
< { Now VIABase has the address of the chip }
° d ONLN dBJ ZV ä (S Z
The point ° d ONLN dLJ äV )0There is that the best way to get the address of a hardware chip is to ask the system ° d ONLN d°V Zb˚ (_ ZTwhere it currently is to be found. The system always knows where the pieces of the ° d ONLN dıV˚b (_˚system ° d ONLN d¸b Zn ¿ (k Zare, and will always ° d ONLN db ¿n )fBknow for every incarnation of the Macintosh. There are low-memory ° d ONLN dTn ZzÅ (w Z=global variables for all of the pieces of hardware currently ° d ONLN dënÅz (wÅ found in the Macintosh. This ° d ONLN dØz ZÜ0 (É Z+includes the VIA, the SCC, the Sound Chip, ° d ONLN d⁄z0Ü )÷-the IWM, and the video display. Whenever you ° d ONLN dÜ Zí‘ (è ZLare stuck with going to the hardware, use the low-memory globals. The fact ° d ONLN dTÜ‘í (è‘that a program ° d ONLN dcí Zûå (õ Z@goes directly to the hardware means that it is risking imminent ° d ONLN d£íåû (õå incompatibility, but using the ° d ONLN d¬û Z™ º (ß Zlow-memory global ° d ONLN d‘û º™ )bGwill ensure that the program has the best odds. It’s like going to Las ° d ONLN d ™ Z∂ Î (≥ Z Vegas: if you don’t gamble at ° d ONLN d;™ Î∂ )ë>all, you don’t lose any money; if you have to gamble, play the ° d ONLN dz∂ Z¬ Ó (ø Z game that you lose the least on. ° d ONLN dõŒ Z⁄ Á *How to find hard attacks ° d ONLN d¥Ê ZÚs *8Run the suspicious program on the Macintosh XL. Nearly ° d ONLN dÏÊsÚ (Ôs%all of the hardware is in a different ° d ONLN dÚ Z˛¶ (˚ ZCmemory location on the XL. If a program has a hard-coded hardware ° d ONLN dUÚ¶˛ (˚¶ address in it, it will fail. ° d ONLN ds˛ Z
{ ( ZIt may ° d ONLN dz˛ {
)!Wcrash, or it might not perform the desired task, but it won’t work as advertised. This ° d ONLN d“
Zfl ( ZOunfortunately, is not a completely legitimate test, since the XL does not have ° d ONLN d !
fl (fl some of the ° d ONLN d - Z"Û ( ZWhardware of other Macintoshes, and some of the hardware that is there has the register ° d ONLN d ÑÛ" ( Ûmapping ° d ONLN d å" Z.Í (+ ZWdifferent. This means that it is possible to play by the rule of using the low-memory ° d ONLN d „"Í. (+Í
global and ° d ONLN d Ó. Z: º (7 Zstill be incompatible. ° d ONLN d
F ZR * Don’t use bits that are reserved ° d ONLN d
(^ ZjÊ *KOccasionally during the life of a Macintosh programmer, there comes a time ° d ONLN d
s^Êj (gÊ
when it is ° d ONLN d
~j Zv (s ZZnecessary to bite the bullet and use a low-memory global. These are very sad days, since ° d ONLN d
ÿjv (sit has ° d ONLN d
flv ZÇë ( Z@been demonstrated (by history) that low-memory global variables ° d ONLN d vëÇ (ë are a mysterious lot, and not ° d ONLN d =É Zè3 (å Z/altogether friendly. One fellow in particular ° d ONLN d lÉ3èu )Ÿ is known as ° d ONLN d xÇuéò )BROM85 ° d ONLN d }Éòè¸ )#, a word located at ° d ONLN d ëǸé )d$28E ° d ONLN d ïÉè ) . ° d ONLN d òè Zõ … (ò ZThis particular variable ° d ONLN d ±è …õ )oChas been documented as the way to determine if a program is running ° d ONLN d ıõ Zß° (§ ZDon the 128K ROMs or not. Notably, the top most bit of that word is ° d ONLN d 9õ°ß (§°the determining bit. This ° d ONLN d Tß Z≥ è (∞ Z means that ° d ONLN d _ß è≥ )5Tthe rest of the bits in that word are reserved, since nothing is described about any ¿ X¿
(’ Z OV 4 - Compatibility: Why & How (’˙19 )
of 21 (Î ZOverview ˇ⁄ HR ˇ ˇˇˇˇ R H
HR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d < 6 H6 *8further bits. Remember, if it doesn’t say, assume it’s ° d ONLN d 8 <6 H¯ ( E6)reserved. If it’s reserved, don’t depend ° d ONLN d b H 6 T ^ ( Q 6 upon it. ° d ONLN d k H ^ T¯ )(T Take the cautious way out and assume that the other bits that aren’t documented are ° d ONLN d ¿ T 6 `= ( ] 68used for Switcher local variables, or something equally ° d ONLN d ¯ T= `¯ ( ]=$wild. An example of a bad way to do ° d ONLN d ` 6 l å ( i 6the comparison is: ,
Courier
° d ONLN d1 x Z É Õ +$VAR Rom85Ptr: WordPtr; ° d ONLN dJ Ç Z ç “ *
RomsAre64: Boolean; ° d ONLN dd ò Z £ü *ARom85Ptr := Pointer ($28E); { point at the low-memory global } ° d ONLN dß ¢ Z ≠ê *
>IF Rom85Ptr^ = $7FFF THEN RomsAre64 := False { Bad test. } ° d ONLN dÁ ¨ Z ∑ “ *
ELSE RomsAre64 := True;
° d ONLN d ¬ 6 Œ u ( À 6This is a bad ° d ONLN d ¬ u Œ^ )?2test since the comparison is testing the value of ° d ONLN d@ ¬^ Œl )Èall ° d ONLN dC ¬l Œ¯ ) of the bits, not only the one ° d ONLN db Œ 6 ⁄á ( ◊ 6Hthat is valid. Since the other bits are undocumented, it is impossible ° d ONLN d™ Œá ⁄¯ ( ◊áto know what they are ° d ONLN d¿ ⁄ 6 ÊD ( „ 67used for. Assume they are used for something that is ° d ONLN d˜ ⁄D ʯ ( „D%arbitrarily random, and take the safe ° d ONLN d Ê 6 Ú ` ( Ô 6way out. ° d ONLN d& ˛ 6
*How to avoid being bitten
° d ONLN dA Z! √ +$VAR ROM85Ptr: Ptr ° d ONLN dX, Z7ü *ARom85Ptr := Pointer ($28E); { point at the low-memory global } ° d ONLN dõ6 ZA∏ *
FIF BitTst(ROM85Ptr,0) THEN RomsAre64 := True {Good--tests only hi-bit} ° d ONLN d„@ ZK ◊ *
ELSE RomsAre64 := False;
° d ONLN d˝V 6b (_ 60This technique will ensure that when those bits ° d ONLN d-Vb¯ )‡+are documented, your program won’t be using ° d ONLN dYb 6n" (k 62them for the wrong things. Beware of trojan bits. ° d ONLN déz 6Ü@ *4Don’t use undocumented stuff. Be very careful when ° d ONLN d¬z@ܯ (É@$you use anything out of the ordinary ° d ONLN dÁá 6ì ” (ê 6"stream of a high-level language. ° d ONLN d á ”ì5 )ùFor instance, in the ° d ONLN d Ü5íX )bROM85 ° d ONLN d#áXì¯ )#" case, it is very easy to make the ° d ONLN dFì 6üß (ú 6Lmistake of checking for an absolute value instead of testing the actual bit ° d ONLN díìßü¯ (úßthat encodes the ° d ONLN d£ü 6´â (® 6>information. Whenever a program is using low-memory globals, ° d ONLN d·üâ´¯ (®âbe sure that only the ° d ONLN d˜´ 6∑| (¥ 6Binformation desired is being used, and not some undocumented (and ° d ONLN d9´|∑¯ (¥|hence reserved) bits. It’s ° d ONLN dU∑ 6√ (¿ 6.not always easy to determine what is reserved ° d ONLN dÉ∑√¯ )„+and what isn’t, so conservative programmers ° d ONLN dØ√ 6œb (à 6@always use as little as possible. Be wary of the strange bits, ° d ONLN dÔ√bœ¯ (Ãb and accept rides from none of ° d ONLN d
œ 6€l (ÿ 6@them. The ride you take might cause you to revise your program. ° d ONLN dNÁ 6Û ¡ *How to find those bitten ° d ONLN dgˇ 6 ü *Since there are such a ° d ONLN d~ˇ ü ¯ )iImultitude of possible places to get killed, there is no simple way to see ° d ONLN d» 6( ( 64what programs are using illegal bits. As time goes ° d ONLN d¸ (¯ )Ú,by it will be possible to find more of these ° d ONLN d) 6# å ( 6cases by running ° d ONLN d: å#¯ )VHon various versions of the Macintosh, but there will probably never be a ° d ONLN dÉ# 6/ ˛ (, 6(comprehensive way of finding out who is ° d ONLN d´# ˛/¯ )»2accepting strange rides, and who is not. Whenever ° d ONLN dfi/ 6;é (8 6Mthe use of a bit changes from reserved status to active, it will be possible ° d ONLN d +/é;¯ (8éto find those bugs via ° d ONLN d B; 6G% (D 62extensive testing. From a source level, it would ° d ONLN d t;%GÙ )Ô(be advisable to look over any use of low ° d ONLN d ú;ÙG¯ )œ- ° d ONLN d ùH 6Tfl (Q 6Zmemory globals, and eye them closely for inappropriate bit usage. Do a global search for ° d ONLN d ˜HflTÒ (Qflthe ° d ONLN d ˚GÒS¯ )$ ° d ONLN d ˝T 6`» (] 6R(which describes those ubiquitous hexadecimal numbers), and when found see if the ° d ONLN d
OT»`¯ (]»
use of the ° d ONLN d
Z` 6ld (i 6Anumber is appropriate. Trust no one that is not known. If they ° d ONLN d
õ`dl¯ (id are documented, they will stay ° d ONLN d
∫l 6xX (u 6<where they are, and have the same meaning. Be very careful ° d ONLN d
ˆlXx¯ (uX in realms that are undocumented. ° d ONLN d x 6ÑÁ (Å 6ZBits that suddenly jump from reserved to active status have been known to cause more than ° d ONLN d rxÁѯ (ÅÁone ° d ONLN d vÑ 6ê5 (ç 65program to have a sudden anxiety attack. It is very ° d ONLN d ´Ñ5ê¯ )ˇ$unnerving to watch a program go from ° d ONLN d –ê 6ú… (ô 6Tcalm and reassuring to rabid status. Users have been known to drop their keyboards ° d ONLN d $ê…ú¯ (ô… in sudden ° d ONLN d .ú 6® Ò (• 6&shock (which is bad on the keyboards). ¿ 4¿˘
*020 )
of 21 (’f OV 4 - Compatibility: Why & How +lOverview ˇB HR ˇ ˇˇˇˇ R H
HR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X /
° d ONLN d H Z W ò ( T ZSummary
° d ONLN d c Z o *\So what does all this mean? It means that it is getting harder and harder to get away with ° d ONLN d d c o ( l minor ° d ONLN d j o Z {… ( x ZLbugs in programs. The minor bugs of yesterday are the major ones of today. ° d ONLN d ∂ o… { ( x… No one will yell ° d ONLN d » { Z áé ( Ñ Z@at you for having bugs in your program, since all programs have ° d ONLN d {é á ( Ñé bugs of one form or another. ° d ONLN d& á Z ì ( ê ZVThe goal should be to make the programs run as smoothly and effortlessly as possible. ° d ONLN d| á ì ( ê The ° d ONLN dÅ ì Z üW ( ú Z4end-users will never object to bug-reduced programs. ° d ONLN d∂ ´ Z ∑ ø *What is the best way ° d ONLN dÀ ´ ø ∑ )eIto test a program? A reasonably comprehensive test is to exercise all of ° d ONLN d ∑ Z √^ ( ¿ Z7the program’s functions under the following situations: ° d ONLN dM œ l € p +• ° d ONLN dO œ y €Î )
NUse Discipline to be sure the program does not pass illegal things to the ROM. ° d ONLN dû € l Á p ( ‰ l• ° d ONLN d† € y Á¡ )
=Use heap scramble and heap purge to be sure that handles are ° d ONLN d› €¡ Á¯ ( ‰¡
being used ° d ONLN dË Á y Û¬ ( yDcorrectly, and that the memory management of the program is correct. ° d ONLN d- Û l ˇ p ( ¸ l• ° d ONLN d/ Û y ˇ )
Run with a checksum on memory ° d ONLN dM Û ˇ¯ )¢/locations 0...3 to see if the program writes to ° d ONLN d} ˇ y ¬ ( ythese locations. ° d ONLN dé l p ( l• ° d ONLN dê yU )
+Run on a 128K Macintosh, or under Switcher ° d ONLN dª U¯ )‹"with a small partition, to see how ° d ONLN dfi y#f ( y2the program deals with memory-critical situations. ° d ONLN d# l/ p (, l• ° d ONLN d# y/ ü )
Run on ° d ONLN d# ü/¯ )&Da 68020 system to see if the program is 68020-compatible and to make ° d ONLN d_/ y;ò (8 y:sure that changing system speed won’t confuse the program. ° d ONLN dö; lG p (D l• ° d ONLN dú; yG ß )
Run on a ° d ONLN d•; ßG¯ ).AMacintosh XL to be sure that the program does not assume too much ° d ONLN dÁG yS (P y8about the operating system, and to test screen handling. ° d ONLN d S l_ p (\ l• ° d ONLN d"S y_ Á )
Run on an Ultra-Large ° d ONLN d8S Á_¯ )n:screen to be sure that the screen handling is correct, and ° d ONLN ds_ ykZ (h y/that there are no hard-coded screen dimensions. ° d ONLN d£k lw p (t l• ° d ONLN d•k yw )
Run on 64K ROM machines to ° d ONLN d¿kw¯ )ñ.be sure new traps are not being used when they ° d ONLN dÔw yÉ Ø (Ä y don’t exist. ° d ONLN d¸É lè p (å l• ° d ONLN d˛É yèI )
&Run under both HFS and MFS to be sure ° d ONLN d$ÉIè¯ )–$that the program deals with the file ° d ONLN dIè yõq (ò y3system correctly. (400K floppies are usually MFS.) ° d ONLN d}ß Z≥ Ø (∞ ZIf a program can ° d ONLN déß Ø≥ )UIlive through all of this with no Discipline traps, no checksum breaks, no ° d ONLN dÿ≥ Zø (º Z[system errors, no anomalies, no data loss and still get useful work done, then you deserve ° d ONLN d3≥ø (ºa ° d ONLN d5ø ZÀ r (» Zgold ° d ONLN d:ø rÀ )Smedal for programming excellence. Maybe even an extra medal for conduct above and ° d ONLN déÀ Z◊… (‘ ZMbeyond the call of duty. In any case, you will know that you have done your ° d ONLN d€À…◊ (‘…job about as well ° d ONLN dÌ◊ Z„Á (‡ ZTas it can be done, with today’s version of the rules, and today’s programming tools. ° d ONLN dBÔ Z˚ ù *Sounds like a ° d ONLN dPÔ ù˚ )CNforeboding task, doesn’t it? The engineers in Macintosh Technical Support are ° d ONLN dü˚ Z € ( Zavailable to help you with ° d ONLN d∫˚ € )Å?compatibility issues (we won’t always be able to talk about new ° d ONLN d˙ Z ( Z&products, since we love our jobs, but ° d ONLN d )∫3we can give you some hints about compatibility with ° d ONLN d T Z Δ ( Zwhat the future holds). ° d ONLN d l+ Z7 ê *
Good luck. ° d ONLN d w[ Zg ƒ *0Further Reference: g Xg ° d ONLN d äh lt p +
• ° d ONLN d åh ~t\ )-Technical Note OV 3 - Compatibility Guidlines ° d ONLN d ∫t lÄ p (} l• ° d ONLN d ºt ~Ä= )%Technical Note OV 15 - Debugging Tips ¿ X¿
